docs(ionicScrollController): write docs

js/ext/angular/src/controller/ionicScrollController.js

@@ -10,6 +10,14 @@ angular.module('ionic.ui.scroll')
   return {};
 })
 
+/**
+ * @ngdoc controller
+ * @name ionicScroll
+ * @module ionic
+ * @description
+ * Controller for the {@link ionic.directive:ionContent} and 
+ * {@link ionic.directive:ionScroll} directives.
+ */
 .controller('$ionicScroll', [
   '$scope',
   'scrollViewOptions',
@@ -90,42 +98,62 @@ function($scope, scrollViewOptions, $timeout, $window, $$scrollValueCache, $loca
   });
 
   this._rememberScrollId = null;
-  this.rememberScrollPosition = function(id) {
-    if (!id) {
-      throw new Error("Must supply an id to remember the scroll by!");
-    }
-    this._rememberScrollId = id;
-  };
-  this.forgetScrollPosition = function() {
-    delete $$scrollValueCache[this._rememberScrollId];
-    this._rememberScrollId = null;
-  };
-  this.scrollToRememberedPosition = function(shouldAnimate) {
-    var values = $$scrollValueCache[this._rememberScrollId];
-    if (values) {
-      scrollView.scrollTo(+values.left, +values.top, shouldAnimate);
-    }
-  };
 
+  /**
+   * @ngdoc method
+   * @name ionicScroll#resize
+   * @description Tell the scrollView to recalculate the size of its container.
+   */
   this.resize = function() {
     return $timeout(resize);
   };
+
+  /**
+   * @ngdoc method
+   * @name ionicScroll#scrollTop
+   * @param {boolean=} shouldAnimate Whether the scroll should animate.
+   */
   this.scrollTop = function(shouldAnimate) {
     this.resize().then(function() {
       scrollView.scrollTo(0, 0, !!shouldAnimate);
     });
   };
+
+  /**
+   * @ngdoc method
+   * @name ionicScroll#scrollBottom
+   * @param {boolean=} shouldAnimate Whether the scroll should animate.
+   */
   this.scrollBottom = function(shouldAnimate) {
     this.resize().then(function() {
       var max = scrollView.getScrollMax();
       scrollView.scrollTo(max.left, max.top, !!shouldAnimate);
     });
   };
+
+  /**
+   * @ngdoc method
+   * @name ionicScroll#scroll
+   * @param {number} left The x-value to scroll to.
+   * @param {number} top The y-value to scroll to.
+   * @param {boolean=} shouldAnimate Whether the scroll should animate.
+   */
   this.scrollTo = function(left, top, shouldAnimate) {
     this.resize().then(function() {
       scrollView.scrollTo(left, top, !!shouldAnimate);
     });
   };
+
+  /**
+   * @ngdoc method
+   * @name ionicScroll#anchorScroll
+   * @description Tell the scrollView to scroll to the element with an id
+   * matching window.location.hash.
+   *
+   * If no matching element is found, it will scroll to top.
+   *
+   * @param {boolean=} shouldAnimate Whether the scroll should animate.
+   */
   this.anchorScroll = function(shouldAnimate) {
     this.resize().then(function() {
       var hash = $location.hash();
@@ -139,6 +167,82 @@ function($scope, scrollViewOptions, $timeout, $window, $$scrollValueCache, $loca
     });
   };
 
+  /**
+   * @ngdoc method
+   * @name ionicScroll#rememberScrollPosition
+   * @description 
+   * Will make it so, when this scrollView is destroyed (user leaves the page),
+   * the last scroll position the page was on will be saved, indexed by the 
+   * given id.
+   *
+   * Note: for pages associated with a view under an ion-nav-view, 
+   * rememberScrollPosition automatically saves their scroll.
+   *
+   * Related methods: scrollToRememberedPosition, forgetScrollPosition (below).
+   *
+   * In the following example, the scroll position of the ion-scroll element
+   * will persist, even when the user changes the toggle switch.
+   *
+   * ```html
+   * <ion-toggle ng-model="shouldShowScrollView"></ion-toggle>
+   * <ion-scroll ng-if="shouldShowScrollView">
+   *   <div ng-controller="ScrollCtrl">
+   *     <ion-list>
+   *       <ion-item ng-repeat="i in items">{{i}}</ion-item>
+   *     </ion-list>
+   *   </div>
+   * </ion-scroll>
+   * ```
+   * ```js
+   * function ScrollCtrl($scope) {
+   *   $scope.$ionicScrollController.rememberScrollPosition('my-scroll-id');
+   *   $scope.$ionicScrollController.scrollToRememberedPosition();
+
+   *   $scope.items = [];
+   *   for (var i=0; i<100; i++) {
+   *     $scope.items.push(i);
+   *   }
+   * }
+   * ```
+   *
+   * @param {string} id The id to remember the scroll position of this 
+   * scrollView by.
+   */
+  this.rememberScrollPosition = function(id) {
+    if (!id) {
+      throw new Error("Must supply an id to remember the scroll by!");
+    }
+    this._rememberScrollId = id;
+  };
+  /**
+   * @ngdoc method
+   * @name ionicScroll#forgetScrollPosition
+   * @description
+   * Stop remembering the scroll position for this scrollView.
+   */
+  this.forgetScrollPosition = function() {
+    delete $$scrollValueCache[this._rememberScrollId];
+    this._rememberScrollId = null;
+  };
+  /**
+   * @ngdoc method
+   * @name ionicScroll#scrollToRememberedPosition
+   * @description
+   * If this scrollView has an id associated with its scroll position,
+   * (through calling rememberScrollPosition), and that position is remembered,
+   * load the position and scroll to it.
+   * @param {boolean=} shouldAnimate Whether to animate the scroll.
+   */
+  this.scrollToRememberedPosition = function(shouldAnimate) {
+    var values = $$scrollValueCache[this._rememberScrollId];
+    if (values) {
+      this.resize().then(function() {
+        scrollView.scrollTo(+values.left, +values.top, shouldAnimate);
+      });
+    }
+  };
+
+
 
   /**
    * @private