From 213e01bd385d418a09b40a88ced0fa79c5940b73 Mon Sep 17 00:00:00 2001
From: Judy Bogart <jbogart@gmail.com>
Date: Fri, 30 Nov 2018 12:16:35 -0800
Subject: [PATCH] docs: add api doc for viewport scroller (#27381)

PR Close #27381
---
 packages/common/src/viewport_scroller.ts | 34 +++++++++++++-----------
 1 file changed, 18 insertions(+), 16 deletions(-)

diff --git a/packages/common/src/viewport_scroller.ts b/packages/common/src/viewport_scroller.ts
index 88a5114d94..09e46f69dc 100644
--- a/packages/common/src/viewport_scroller.ts
+++ b/packages/common/src/viewport_scroller.ts
@@ -11,7 +11,7 @@ import {defineInjectable, inject} from '@angular/core';
 import {DOCUMENT} from './dom_tokens';
 
 /**
- * Manages the scroll position.
+ * Defines a scroll position manager. Implemented by `BrowserViewportScroller`.
  *
  * @publicApi
  */
@@ -24,40 +24,40 @@ export abstract class ViewportScroller {
 
   /**
    * Configures the top offset used when scrolling to an anchor.
+   * @param offset A position in screen coordinates (a tuple with x and y values)
+   * or a function that returns the top offset position.
    *
-   * When given a tuple with two number, the service will always use the numbers.
-   * When given a function, the service will invoke the function every time it restores scroll
-   * position.
    */
   abstract setOffset(offset: [number, number]|(() => [number, number])): void;
 
   /**
-   * Returns the current scroll position.
+   * Retrieves the current scroll position.
+   * @returns A position in screen coordinates (a tuple with x and y values).
    */
   abstract getScrollPosition(): [number, number];
 
   /**
-   * Sets the scroll position.
+   * Scrolls to a specified position.
+   * @param position A position in screen coordinates (a tuple with x and y values).
    */
   abstract scrollToPosition(position: [number, number]): void;
 
   /**
-   * Scrolls to the provided anchor.
+   * Scrolls to an anchor element.
+   * @param anchor The ID of the anchor element.
    */
   abstract scrollToAnchor(anchor: string): void;
 
   /**
-   *
    * Disables automatic scroll restoration provided by the browser.
-   *
    * See also [window.history.scrollRestoration
-   * info](https://developers.google.com/web/updates/2015/09/history-api-scroll-restoration)
+   * info](https://developers.google.com/web/updates/2015/09/history-api-scroll-restoration).
    */
   abstract setHistoryScrollRestoration(scrollRestoration: 'auto'|'manual'): void;
 }
 
 /**
- * Manages the scroll position.
+ * Manages the scroll position for a browser window.
  */
 export class BrowserViewportScroller implements ViewportScroller {
   private offset: () => [number, number] = () => [0, 0];
@@ -66,10 +66,9 @@ export class BrowserViewportScroller implements ViewportScroller {
 
   /**
    * Configures the top offset used when scrolling to an anchor.
+   * @param offset A position in screen coordinates (a tuple with x and y values)
+   * or a function that returns the top offset position.
    *
-   * * When given a number, the service will always use the number.
-   * * When given a function, the service will invoke the function every time it restores scroll
-   * position.
    */
   setOffset(offset: [number, number]|(() => [number, number])): void {
     if (Array.isArray(offset)) {
@@ -80,7 +79,8 @@ export class BrowserViewportScroller implements ViewportScroller {
   }
 
   /**
-   * Returns the current scroll position.
+   * Retrieves the current scroll position.
+   * @returns The position in screen coordinates.
    */
   getScrollPosition(): [number, number] {
     if (this.supportScrollRestoration()) {
@@ -92,6 +92,7 @@ export class BrowserViewportScroller implements ViewportScroller {
 
   /**
    * Sets the scroll position.
+   * @param position The new position in screen coordinates.
    */
   scrollToPosition(position: [number, number]): void {
     if (this.supportScrollRestoration()) {
@@ -100,7 +101,8 @@ export class BrowserViewportScroller implements ViewportScroller {
   }
 
   /**
-   * Scrolls to the provided anchor.
+   * Scrolls to an anchor element.
+   * @param anchor The ID of the anchor element.
    */
   scrollToAnchor(anchor: string): void {
     if (this.supportScrollRestoration()) {