doc(API): various API documentation improvements

3 files changed, 221 insertions, 179 deletions

diff --git a/src/Angular.js b/src/Angular.js
index d5131c1f..1952b48e 100644
--- a/src/Angular.js
+++ b/src/Angular.js
@@ -44,8 +44,8 @@ var manualUppercase = function (s) {
 
 
 // String#toLowerCase and String#toUpperCase don't produce correct results in browsers with Turkish
-// locale, for this reason we need to detect this case and redefine lowercase/uppercase methods with
-// correct but slower alternatives.
+// locale, for this reason we need to detect this case and redefine lowercase/uppercase methods
+// with correct but slower alternatives.
 if ('i' !== 'I'.toLowerCase()) {
   lowercase = manualLowercase;
   uppercase = manualUppercase;
@@ -118,10 +118,11 @@ var _undefined        = undefined,
  * @function
  *
  * @description
- * Invokes the `iterator` function once for each item in `obj` collection. The collection can either
- * be an object or an array. The `iterator` function is invoked with `iterator(value, key)`, where
- * `value` is the value of an object property or an array element and `key` is the object property
- * key or array element index. Optionally, `context` can be specified for the iterator function.
+ * Invokes the `iterator` function once for each item in `obj` collection. The collection can
+ * either be an object or an array. The `iterator` function is invoked with `iterator(value, key)`,
+ * where `value` is the value of an object property or an array element and `key` is the object
+ * property key or array element index. Optionally, `context` can be specified for the iterator
+ * function.
  *
  * Note: this function was previously known as `angular.foreach`.
  *
@@ -222,8 +223,8 @@ function nextUid() {
  * @function
  *
  * @description
- * Extends the destination object `dst` by copying all of the properties from the `src` object(s) to
- * `dst`. You can specify multiple `src` objects.
+ * Extends the destination object `dst` by copying all of the properties from the `src` object(s)
+ * to `dst`. You can specify multiple `src` objects.
  *
  * @param {Object} dst The destination object.
  * @param {...Object} src The source object(s).
@@ -428,9 +429,13 @@ function isWindow(obj) {
   return obj && obj.document && obj.location && obj.alert && obj.setInterval;
 }
 
-function isBoolean(value) { return typeof value == $boolean;}
+function isBoolean(value) { return typeof value == $boolean; }
 function isTextNode(node) { return nodeName_(node) == '#text'; }
-function trim(value) { return isString(value) ? value.replace(/^\s*/, '').replace(/\s*$/, '') : value; }
+
+function trim(value) {
+  return isString(value) ? value.replace(/^\s*/, '').replace(/\s*$/, '') : value;
+}
+
 function isElement(node) {
   return node &&
     (node.nodeName  // we are a direct element
@@ -451,10 +456,12 @@ function makeMap(str){
 
 
 /**
- * HTML class which is the only class which can be used in ng:bind to inline HTML for security reasons.
+ * HTML class which is the only class which can be used in ng:bind to inline HTML for security
+ * reasons.
+ *
  * @constructor
  * @param html raw (unsafe) html
- * @param {string=} option if set to 'usafe' then get method will return raw (unsafe/unsanitized) html
+ * @param {string=} option If set to 'usafe', get method will return raw (unsafe/unsanitized) html
  */
 function HTML(html, option) {
   this.html = html;
@@ -470,7 +477,8 @@ function HTML(html, option) {
 if (msie < 9) {
   nodeName_ = function(element) {
     element = element.nodeName ? element : element[0];
-    return (element.scopeName && element.scopeName != 'HTML' ) ? uppercase(element.scopeName + ':' + element.nodeName) : element.nodeName;
+    return (element.scopeName && element.scopeName != 'HTML')
+      ? uppercase(element.scopeName + ':' + element.nodeName) : element.nodeName;
   };
 } else {
   nodeName_ = function(element) {
@@ -500,26 +508,35 @@ function map(obj, iterator, context) {
  * @function
  *
  * @description
- * Determines the number of elements in an array, number of properties of an object or string
- * length.
+ * Determines the number of elements in an array, the number of properties an object has, or
+ * the length of a string.
  *
- * Note: this function is used to augment the Object type in angular expressions. See
- * {@link angular.Object} for more info.
+ * Note: This function is used to augment the Object type in Angular expressions. See
+ * {@link angular.Object} for more information about Angular arrays.
  *
- * @param {Object|Array|string} obj Object, array or string to inspect.
+ * @param {Object|Array|string} obj Object, array, or string to inspect.
  * @param {boolean} [ownPropsOnly=false] Count only "own" properties in an object
  * @returns {number} The size of `obj` or `0` if `obj` is neither an object or an array.
  *
  * @example
  * <doc:example>
  *  <doc:source>
- *   Number of items in array: {{ [1,2].$size() }}<br/>
- *   Number of items in object: {{ {a:1, b:2, c:3}.$size() }}<br/>
+ *   <script>
+ *     function SizeCtrl() {
+ *       this.fooStringLength = angular.Object.size('foo');
+ *     }
+ *   </script>
+ *   <div ng:controller="SizeCtrl">
+ *     Number of items in array: {{ [1,2].$size() }}<br/>
+ *     Number of items in object: {{ {a:1, b:2, c:3}.$size() }}<br/>
+ *     String length: {{fooStringLength}}
+ *   </div>
  *  </doc:source>
  *  <doc:scenario>
  *   it('should print correct sizes for an array and an object', function() {
  *     expect(binding('[1,2].$size()')).toBe('2');
  *     expect(binding('{a:1, b:2, c:3}.$size()')).toBe('3');
+ *     expect(binding('fooStringLength')).toBe('3');
  *   });
  *  </doc:scenario>
  * </doc:example>
@@ -581,24 +598,21 @@ function isLeafNode (node) {
  * @function
  *
  * @description
- * Creates a deep copy of `source`.
+ * Creates a deep copy of `source`, which should be an object or an array.
  *
- * If `source` is an object or an array, all of its members will be copied into the `destination`
- * object.
+ * * If no destination is supplied, a copy of the object or array is created.
+ * * If a destination is provided, all of its elements (for array) or properties (for objects)
+ *   are deleted and then all elements/properties from the source are copied to it.
+ * * If  `source` is not an object or array, `source` is returned.
  *
- * If `destination` is not provided and `source` is an object or an array, a copy is created &
- * returned, otherwise the `source` is returned.
+ * Note: this function is used to augment the Object type in Angular expressions. See
+ * {@link angular.Array} for more information about Angular arrays.
  *
- * If `destination` is provided, all of its properties will be deleted.
- *
- * Note: this function is used to augment the Object type in angular expressions. See
- * {@link angular.Object} for more info.
- *
- * @param {*} source The source to be used to make a copy.
- *                   Can be any type including primitives, `null` and `undefined`.
- * @param {(Object|Array)=} destination Optional destination into which the source is copied. If
+ * @param {*} source The source that will be used to make a copy.
+ *                   Can be any type, including primitives, `null`, and `undefined`.
+ * @param {(Object|Array)=} destination Destination into which the source is copied. If
  *     provided, must be of the same type as `source`.
- * @returns {*} The copy or updated `destination` if `destination` was specified.
+ * @returns {*} The copy or updated `destination`, if `destination` was specified.
  *
  * @example
  * <doc:example>
@@ -660,7 +674,6 @@ function copy(source, destination){
 }
 
 /**
- * @workInProgress
  * @ngdoc function
  * @name angular.equals
  * @function
@@ -675,16 +688,19 @@ function copy(source, destination){
  * @function
  *
  * @description
- * Determines if two objects or value are equivalent.
+ * Determines if two objects or two values are equivalent. Supports value types, arrays and
+ * objects.
  *
- * To be equivalent, they must pass `===` comparison or be of the same type and have all their
- * properties pass `===` comparison. During property comparision properties of `function` type and
- * properties with name starting with `$` are ignored.
+ * Two objects or values are considered equivalent if at least one of the following is true:
  *
- * Supports values types, arrays and objects.
+ * * Both objects or values pass `===` comparison.
+ * * Both objects or values are of the same type and all of their properties pass `===` comparison.
  *
- * Note: this function is used to augment the Object type in angular expressions. See
- * {@link angular.Object} for more info.
+ * During a property comparision, properties of `function` type and properties with names
+ * that begin with `$` are ignored.
+ *
+ * Note: This function is used to augment the Object type in Angular expressions. See
+ * {@link angular.Array} for more information about Angular arrays.
  *
  * @param {*} o1 Object or value to compare.
  * @param {*} o2 Object or value to compare.
@@ -732,7 +748,9 @@ function equals(o1, o2) {
     } else {
       keySet = {};
       for(key in o1) {
-        if (key.charAt(0) !== '$' && !isFunction(o1[key]) && !equals(o1[key], o2[key])) return false;
+        if (key.charAt(0) !== '$' && !isFunction(o1[key]) && !equals(o1[key], o2[key])) {
+          return false;
+        }
         keySet[key] = true;
       }
       for(key in o2) {
@@ -802,7 +820,9 @@ function sliceArgs(args, startIndex) {
  * @function
  *
  * @description
- * Returns a function which calls function `fn` bound to `self` (`self` becomes the `this` for `fn`).
+ * Returns a function which calls function `fn` bound to `self`
+ * (`self` becomes the `this` for `fn`).
+ *
  * Optional `args` can be supplied which are prebound to the function, also known as
  * [function currying](http://en.wikipedia.org/wiki/Currying).
  *
@@ -826,7 +846,8 @@ function bind(self, fn) {
             : fn.call(self);
         };
   } else {
-    // in IE, native methods are not functions and so they can not be bound (but they don't need to be)
+    // in IE, native methods are not functions and so they can not be bound
+    // (but they don't need to be)
     return fn;
   }
 }
@@ -928,7 +949,6 @@ function encodeUriQuery(val, pctEncodeSpaces) {
 
 
 /**
- * @workInProgress
  * @ngdoc directive
  * @name angular.directive.ng:autobind
  * @element script
@@ -938,14 +958,17 @@ function encodeUriQuery(val, pctEncodeSpaces) {
  * @TODO rename to ng:autobind to ng:autoboot
  *
  * @description
+ * Technically, ng:autobind is not a directive; it is an Angular bootstrap parameter that can act
+ * as a directive. It must exist in the script used to boot Angular and can be used only one time.
+ * For details on bootstrapping Angular, see {@link guide/dev_guide.bootstrap Initializing Angular}
+ * in the Angular Developer Guide.
  *
- * `ng:autobind` with no parameters tells angular to compile and manage the whole page.
+ * `ng:autobind` with no parameters tells Angular to compile and manage the whole page.
  *
- * `ng:autobind="[root element ID]"` tells angular to compile and manage part of the docucment,
+ * `ng:autobind="[root element ID]"` tells Angular to compile and manage part of the document,
  * starting at "root element ID".
  *
- * For details on bootstrapping angular, see {@link guide/dev_guide.bootstrap Initializing Angular}
- * in the Angular Developer Guide.
+
  */
 function angularInit(config, document){
   var autobind = config.autobind;
diff --git a/src/apis.js b/src/apis.js
index 10cccacf..9f081012 100644
--- a/src/apis.js
+++ b/src/apis.js
@@ -23,18 +23,20 @@ var angularGlobal = {
  * A namespace for utility functions used to work with JavaScript objects. These functions are
  * exposed in two ways:
  *
- * __* Angular expressions:__ Functions are bound to all objects and augment the Object type. The
- * names of these methods are prefixed with the '$' character in order to minimize naming collisions.
- * To call a method, invoke the function without the first argument, e.g, `myObject.$foo(param2)`.
+ * * __Angular expressions:__ Functions are bound to all objects and augment the Object type.
+ * The names of these methods are prefixed with the '$' character in order to minimize naming
+ * collisions. To call a method, invoke the function without the first argument, for example,
+ * `myObject.$foo(param2)`.
  *
- * __* JavaScript code:__ Functions don't augment the Object type and must be invoked as functions of
- * `angular.Object` as `angular.Object.foo(myObject, param2)`.
+ * * __JavaScript code:__ Functions don't augment the Object type and must be invoked as functions
+ * of `angular.Object` as `angular.Object.foo(myObject, param2)`.
  *
- * * {@link angular.Object.copy angular.Object.copy()} - Creates a deep copy of the source parameter
- * * {@link angular.Object.equals angular.Object.equals()} - Determines if two objects or values are
- * equivalent
- * * {@link angular.Object.size angular.Object.size()} - Determines the number of elements in
- * strings, arrays, and objects.
+ *   * {@link angular.Object.copy angular.Object.copy()} - Creates a deep copy of the source
+ *     parameter.
+ *   * {@link angular.Object.equals angular.Object.equals()} - Determines if two objects or values
+ *     are equivalent.
+ *   * {@link angular.Object.size angular.Object.size()} - Determines the number of elements in
+ *     strings, arrays, and objects.
  */
 var angularCollection = {
   'copy': copy,
@@ -54,28 +56,30 @@ var angularObject = {
  *
  * These functions are exposed in two ways:
  *
- * * __Angular expressions:__ Functions are bound to the Array objects and augment the Array type as
- * array methods. The names of these methods are prefixed with $ character to minimize naming
- * collisions. To call a method, invoke myArrayObject.$foo(params).
+ * * __Angular expressions:__ Functions are bound to the Array objects and augment the Array type
+ * as array methods. The names of these methods are prefixed with the `$` character to minimize
+ * naming collisions. To call a method, invoke myArrayObject.$foo(params).
  *
  *     Because Array type is a subtype of the Object type, all angular.Object functions augment
- *     theArray type in angular expressions as well.
+ *     the Array type in Angular expressions as well.
  *
- * * __JavaScript code:__ Functions don't augment the Array type and must be invoked as functions of
- * `angular.Array` as `angular.Array.foo(myArrayObject, params)`.
+ * * __JavaScript code:__ Functions do nor augment the Array type and must be invoked as functions
+ * of `angular.Array` as `angular.Array.foo(myArrayObject, params)`.
  *
- * The following APIs are built-in to the angular Array object:
+ * The following APIs are built in to the Angular Array object:
  *
  * * {@link angular.Array.add angular.Array.add()} - Optionally adds a new element to an array.
  * * {@link angular.Array.count angular.Array.count()} - Determines the number of elements in an
- * array.
- * * {@link angular.Array.filter angular.Array.filter()} - Returns a subset of items as a new array.
- * * {@link angular.Array.indexOf angular.Array.indexOf()} - Determines the index of an array value.
- * * {@link angular.Array.limitTo angular.Array.limitTo()} - Creates a new array off the front or
- * back of an existing array.
- * * {@link angular.Array.orderBy angular.Array.orderBy()} - Orders array elements
- * * {@link angular.Array.remove angular.Array.remove()} - Removes array elements
- * * {@link angular.Array.sum angular.Array.sum()} - Sums the number elements in an array
+ *                                                       array.
+ * * {@link angular.Array.filter angular.Array.filter()} - Returns the subset of elements specified
+ *                                                         in the filter as a new array.
+ * * {@link angular.Array.indexOf angular.Array.indexOf()} - Determines the index of an array
+ *                                                           value.
+ * * {@link angular.Array.limitTo angular.Array.limitTo()} - Creates a sub-array of an existing
+ *                                                           array.
+ * * {@link angular.Array.orderBy angular.Array.orderBy()} - Orders array elements.
+ * * {@link angular.Array.remove angular.Array.remove()} - Removes array elements.
+ * * {@link angular.Array.sum angular.Array.sum()} - Sums the numbers in an array.
  */
 var angularArray = {
 
@@ -86,14 +90,15 @@ var angularArray = {
    * @function
    *
    * @description
-   * Determines the index of `value` in `array`.
+   * Determines the index of a `value` in an `array`.
    *
-   * Note: this function is used to augment the `Array` type in angular expressions. See
-   * {@link angular.Array} for more info.
+   * Note: This function is used to augment the `Array` type in Angular expressions. See
+   * {@link angular.Array} for more information about Angular arrays.
    *
    * @param {Array} array Array to search.
    * @param {*} value Value to search for.
-   * @returns {number} The position of the element in `array`. The position is 0-based. `-1` is returned if the value can't be found.
+   * @returns {number} The position of the element in `array`. The position is 0-based.
+   * If the value cannot be found, `-1` is returned.
    *
    * @example
       <doc:example>
@@ -126,38 +131,39 @@ var angularArray = {
    * @function
    *
    * @description
-   * This function calculates the sum of all numbers in `array`. If the `expressions` is supplied,
-   * it is evaluated once for each element in `array` and then the sum of these values is returned.
+   * The `sum` function calculates the sum of all numbers in an `array`. If an `expression` is
+   * supplied, `sum` evaluates each element in the `array` with the expression and then returns
+   * the sum of the calculated values.
    *
-   * Note: this function is used to augment the `Array` type in angular expressions. See
-   * {@link angular.Array} for more info.
+   * Note: This function is used to augment the `Array` type in Angular expressions. See
+   * {@link angular.Array} for more info about Angular arrays.
    *
    * @param {Array} array The source array.
-   * @param {(string|function())=} expression Angular expression or a function to be evaluated for each
-   *     element in `array`. The array element becomes the `this` during the evaluation.
+   * @param {(string|function())=} expression Angular expression or a function to be evaluated for
+   *  each element in `array`. The array element becomes the `this` during the evaluation.
    * @returns {number} Sum of items in the array.
    *
    * @example
       <doc:example>
-        <doc:source>
-         <table ng:init="invoice= {items:[{qty:10, description:'gadget', cost:9.95}]}">
-           <tr><th>Qty</th><th>Description</th><th>Cost</th><th>Total</th><th></th></tr>
-           <tr ng:repeat="item in invoice.items">
-             <td><input name="item.qty" value="1" size="4" ng:required ng:validate="integer"></td>
-            <td><input name="item.description"></td>
-              <td><input name="item.cost" value="0.00" ng:required ng:validate="number" size="6"></td>
-             <td>{{item.qty * item.cost | currency}}</td>
-             <td>[<a href ng:click="invoice.items.$remove(item)">X</a>]</td>
-           </tr>
-           <tr>
-             <td><a href ng:click="invoice.items.$add()">add item</a></td>
-             <td></td>
-             <td>Total:</td>
-             <td>{{invoice.items.$sum('qty*cost') | currency}}</td>
-           </tr>
-         </table>
-        </doc:source>
-        <doc:scenario>
+       <doc:source>
+        <table ng:init="invoice= {items:[{qty:10, description:'gadget', cost:9.95}]}">
+         <tr><th>Qty</th><th>Description</th><th>Cost</th><th>Total</th><th></th></tr>
+         <tr ng:repeat="item in invoice.items">
+           <td><input name="item.qty" value="1" size="4" ng:required ng:validate="integer"></td>
+           <td><input name="item.description"></td>
+           <td><input name="item.cost" value="0.00" ng:required ng:validate="number" size="6"></td>
+           <td>{{item.qty * item.cost | currency}}</td>
+           <td>[<a href ng:click="invoice.items.$remove(item)">X</a>]</td>
+         </tr>
+         <tr>
+           <td><a href ng:click="invoice.items.$add()">add item</a></td>
+           <td></td>
+           <td>Total:</td>
+           <td>{{invoice.items.$sum('qty*cost') | currency}}</td>
+         </tr>
+        </table>
+       </doc:source>
+       <doc:scenario>
          //TODO: these specs are lame because I had to work around issues #164 and #167
          it('should initialize and calculate the totals', function() {
            expect(repeater('.doc-example-live table tr', 'item in invoice.items').count()).toBe(3);
@@ -176,7 +182,7 @@ var angularArray = {
              toEqual(['$2,000.00']);
            expect(binding("invoice.items.$sum('qty*cost')")).toBe('$2,099.50');
          });
-        </doc:scenario>
+       </doc:scenario>
       </doc:example>
    */
   'sum':function(array, expression) {
@@ -202,8 +208,8 @@ var angularArray = {
    * {@link angular.Array.indexOf indexOf} function on the `array` and only the first instance of
    * the element will be removed.
    *
-   * Note: this function is used to augment the `Array` type in angular expressions. See
-   * {@link angular.Array} for more info.
+   * Note: This function is used to augment the `Array` type in Angular expressions. See
+   * {@link angular.Array} for more information about Angular arrays.
    *
    * @param {Array} array Array from which an element should be removed.
    * @param {*} value Element to be removed.
@@ -258,8 +264,8 @@ var angularArray = {
    * @description
    * Selects a subset of items from `array` and returns it as a new array.
    *
-   * Note: this function is used to augment the `Array` type in angular expressions. See
-   * {@link angular.Array} for more info.
+   * Note: This function is used to augment the `Array` type in Angular expressions. See
+   * {@link angular.Array} for more information about Angular arrays.
    *
    * @param {Array} array The source array.
    * @param {string|Object|function()} expression The predicate to be used for selecting items from
@@ -412,28 +418,28 @@ var angularArray = {
 
 
   /**
-   * @workInProgress
    * @ngdoc function
    * @name angular.Array.add
    * @function
    *
    * @description
-   * `add` is a function similar to JavaScript's `Array#push` method, in that it appends a new
-   * element to an array. The difference is that the value being added is optional and defaults to
-   * an empty object.
+   * The `add` function in Angualar is similar to JavaScript's `Array#push` method in that it
+   * appends a new element to an array. Angular's function differs from the JavaScript method in
+   * that specifying a value for the function is optional and the default for the function is an
+   * empty object.
    *
-   * Note: this function is used to augment the `Array` type in angular expressions. See
-   * {@link angular.Array} for more info.
+   * Note: This function is used to augment the `Array` type in Angular expressions. See
+   * {@link angular.Array} for more information about Angular arrays.
    *
-   * @param {Array} array The array expand.
-   * @param {*=} [value={}] The value to be added.
+   * @param {Array} array The array to be expanded.
+   * @param {*=} [value={}] The value to be appended.
    * @returns {Array} The expanded array.
    *
    * @TODO simplify the example.
    *
    * @example
-   * This example shows how an initially empty array can be filled with objects created from user
-   * input via the `$add` method.
+   * This example shows how you can use the `$add` method to populate an initially empty array
+   * with objects created from user input.
      <doc:example>
        <doc:source>
          [<a href="" ng:click="people.$add()">add empty</a>]
@@ -493,17 +499,18 @@ var angularArray = {
    * @function
    *
    * @description
-   * Determines the number of elements in an array. Optionally it will count only those elements
-   * for which the `condition` evaluates to `true`.
+   * Determines the number of elements in an array. Provides an option for counting only those
+   * elements for which a specified `condition` evaluates to `true`.
    *
-   * Note: this function is used to augment the `Array` type in angular expressions. See
-   * {@link angular.Array} for more info.
+   * Note: This function is used to augment the `Array` type in Angular expressions. See
+   * {@link angular.Array} for more information about Angular arrays.
    *
-   * @param {Array} array The array to count elements in.
-   * @param {(function()|string)=} condition A function to be evaluated or angular expression to be
-   *     compiled and evaluated. The element that is currently being iterated over, is exposed to
-   *     the `condition` as `this`.
-   * @returns {number} Number of elements in the array (for which the condition evaluates to true).
+   * @param {Array} array The array containing the elements to be counted.
+   * @param {(function()|string)=} condition A function to be evaluated or
+   *     an Angular expression to be compiled and evaluated. The element being
+   *     iterated over is exposed to the `condition` as `this`.
+   * @returns {number} Number of elements in the array. If a `condition` is specified, returns
+   * the number of elements whose `condition` evaluates to `true`.
    *
    * @example
      <doc:example>
@@ -518,7 +525,8 @@ var angularArray = {
            </li>
          </ul>
          <p>Number of items which have one point: <em>{{ items.$count('points==1') }}</em></p>
-         <p>Number of items which have more than one point: <em>{{items.$count('points&gt;1')}}</em></p>
+         <p>Number of items which have more than one point:
+         <em>{{items.$count('points&gt;1')}}</em></p>
        </doc:source>
        <doc:scenario>
          it('should calculate counts', function() {
@@ -552,10 +560,10 @@ var angularArray = {
    * @function
    *
    * @description
-   * Orders `array` by the `expression` predicate.
+   * Orders a specified `array` by the `expression` predicate.
    *
-   * Note: this function is used to augment the `Array` type in angular expressions. See
-   * {@link angular.Array} for more info.
+   * Note: this function is used to augment the `Array` type in Angular expressions. See
+   * {@link angular.Array} for more informaton about Angular arrays.
    *
    * @param {Array} array The array to sort.
    * @param {function(*)|string|Array.<(function(*)|string)>} expression A predicate to be
@@ -563,13 +571,13 @@ var angularArray = {
    *
    *    Can be one of:
    *
-   *    - `function`: getter function. The result of this function will be sorted using the
-   *      `<`, `=`, `>` operator
-   *    - `string`: angular expression which evaluates to an object to order by, such as 'name' to
-   *      sort by a property called 'name'. Optionally prefixed with `+` or `-` to control ascending
-   *      or descending sort order (e.g. +name or -name).
-   *    - `Array`: array of function or string predicates, such that a first predicate in the array
-   *      is used for sorting, but when the items are equivalent next predicate is used.
+   *    - `function`: Getter function. The result of this function will be sorted using the
+   *      `<`, `=`, `>` operator.
+   *    - `string`: An Angular expression which evaluates to an object to order by, such as 'name'
+   *      to sort by a property called 'name'. Optionally prefixed with `+` or `-` to control
+   *      ascending or descending sort order (for example, +name or -name).
+   *    - `Array`: An array of function or string predicates. The first predicate in the array
+   *      is used for sorting, but when two items are equivalent, the next predicate is used.
    *
    * @param {boolean=} reverse Reverse the order the array.
    * @returns {Array} Sorted copy of the source array.
@@ -678,16 +686,18 @@ var angularArray = {
    * @function
    *
    * @description
-   * Creates a new array containing only the first, or last `limit` number of elements of the
-   * source `array`.
+   * Creates a new array containing only a specified number of elements in an array. The elements
+   * are taken from either the beginning or the end of the source array, as specified by the
+   * value and sign (positive or negative) of `limit`.
    *
-   * Note: this function is used to augment the `Array` type in angular expressions. See
-   * {@link angular.Array} for more info.
+   * Note: This function is used to augment the `Array` type in Angular expressions. See
+   * {@link angular.Array} for more information about Angular arrays.
    *
    * @param {Array} array Source array to be limited.
-   * @param {string|Number} limit The length of the returned array. If the number is positive, the
-   *     first `limit` items from the source array will be copied, if the number is negative, the
-   *     last `limit` items will be copied.
+   * @param {string|Number} limit The length of the returned array. If the `limit` number is
+   *     positive, `limit` number of items from the beginning of the source array are copied.
+   *     If the number is negative, `limit` number  of items from the end of the source array are
+   *     copied.
    * @returns {Array} A new sub-array of length `limit`.
    *
    * @example
@@ -761,7 +771,9 @@ var angularString = {
   },
 
   /**
-   * Tries to convert input to date and if successful returns the date, otherwise returns the input.
+   * Tries to convert input to date and if successful returns the date, otherwise returns the
+   * input.
+   *
    * @param {string} string
    * @return {(Date|string)}
    */
diff --git a/src/directives.js b/src/directives.js
index 7edbbd6f..2ca7b79b 100644
--- a/src/directives.js
+++ b/src/directives.js
@@ -1,44 +1,46 @@
 'use strict';
 
 /**
- * @workInProgress
  * @ngdoc overview
  * @name angular.directive
  * @description
  *
- * Custom attributes for DOM elements.  Directives modify the behavior of the element they are
- * specified in, but are not intended to add elements to the DOM as are
- * {@link angular.widget widgets}.
+ * Angular directives create custom attributes for DOM elements. A directive can modify the
+ * behavior of the element in which it is specified. Do not use directives to add elements to the
+ * DOM; instead, use {@link angular.widget widgets} to add DOM elements.
  *
- * Following is the list of built-in angular directives:
+ * Following is the list of built-in Angular directives:
  *
- * * {@link angular.directive.ng:bind ng:bind} - Creates a data-binding between HTML text value and
- * data model.
- * * {@link angular.directive.ng:bind-attr ng:bind-attr} - Creates a data-binding as in `ng:bind`,
- * but uses JSON key / value pairs.
- * * {@link angular.directive.ng:bind-template ng:bind-template} - Replaces text value of an element
- * with a specified template.
+ * * {@link angular.directive.ng:autobind ng:autobind} - An Angular bootstrap parameter that can
+ * act as a directive.
+ * * {@link angular.directive.ng:bind ng:bind} - Creates a data-binding between an HTML text value
+ * and a data model.
+ * * {@link angular.directive.ng:bind-attr ng:bind-attr} - Creates a data-binding in a way similar
+ * to `ng:bind`, but uses JSON key / value pairs to do so.
+ * * {@link angular.directive.ng:bind-template ng:bind-template} - Replaces the text value of an
+ * element with a specified template.
  * * {@link angular.directive.ng:change ng:change} - Executes an expression when the value of an
  * input widget changes.
- * * {@link angular.directive.ng:class ng:class} - Conditionally set CSS class on an element.
+ * * {@link angular.directive.ng:class ng:class} - Conditionally set a CSS class on an element.
  * * {@link angular.directive.ng:class-even ng:class-even} - Like `ng:class`, but works in
  * conjunction with {@link angular.widget.@ng:repeat} to affect even rows in a collection.
  * * {@link angular.directive.ng:class-odd ng:class-odd} - Like `ng:class`, but works with {@link
  * angular.widget.@ng:repeat}  to affect odd rows.
- * * {@link angular.directive.ng:click ng:click} - Executes custom behavior when element is clicked.
+ * * {@link angular.directive.ng:click ng:click} - Executes custom behavior when an element is
+ * clicked.
  * * {@link angular.directive.ng:controller ng:controller} - Creates a scope object linked to the
  * DOM element and assigns behavior to the scope.
  * * {@link angular.directive.ng:hide ng:hide} - Conditionally hides a portion of HTML.
- * * {@link angular.directive.ng:href ng:href} - Places an href in the angular namespace.
+ * * {@link angular.directive.ng:href ng:href} - Places an href in the Angular namespace.
  * * {@link angular.directive.ng:init} - Initialization tasks run before a template is executed.
  * * {@link angular.directive.ng:show ng:show} - Conditionally displays a portion of HTML.
- * * {@link angular.directive.ng:src ng:src} - Places a `src` attribute into the angular namespace.
+ * * {@link angular.directive.ng:src ng:src} - Places a `src` attribute into the Angular namespace.
  * * {@link angular.directive.ng:style ng:style} - Conditionally set CSS styles on an element.
- * * {@link angular.directive.ng:submit} - Binds angular expressions to `onSubmit` events.
+ * * {@link angular.directive.ng:submit} - Binds Angular expressions to `onSubmit` events.
  *
- * For more information about how angular directives work, and how to create your own directives,
- * see {@link guide/dev_guide.compiler.directives Understanding Angular Directives} in the angular
- * Developer Guide.
+ * For more information about how Angular directives work, and to learn how to create your own
+ * directives, see {@link guide/dev_guide.compiler.directives Understanding Angular Directives} in
+ * the Angular Developer Guide.
  */
 
 /**
@@ -151,12 +153,17 @@ angularDirective("ng:init", function(expression){
      <doc:scenario>
        it('should check controller', function(){
          expect(element('.doc-example-live div>:input').val()).toBe('John Smith');
-         expect(element('.doc-example-live li[ng\\:repeat-index="0"] input').val()).toBe('408 555 1212');
-         expect(element('.doc-example-live li[ng\\:repeat-index="1"] input').val()).toBe('john.smith@example.org');
+         expect(element('.doc-example-live li[ng\\:repeat-index="0"] input').val())
+           .toBe('408 555 1212');
+         expect(element('.doc-example-live li[ng\\:repeat-index="1"] input').val())
+           .toBe('john.smith@example.org');
+
          element('.doc-example-live li:first a:contains("clear")').click();
          expect(element('.doc-example-live li:first input').val()).toBe('');
+
          element('.doc-example-live li:last a:contains("add")').click();
-         expect(element('.doc-example-live li[ng\\:repeat-index="2"] input').val()).toBe('yourname@example.org');
+         expect(element('.doc-example-live li[ng\\:repeat-index="2"] input').val())
+           .toBe('yourname@example.org');
        });
      </doc:scenario>
    </doc:example>
@@ -173,22 +180,21 @@ angularDirective("ng:controller", function(expression){
 });
 
 /**
- * @workInProgress
  * @ngdoc directive
  * @name angular.directive.ng:bind
  *
  * @description
- * The `ng:bind` attribute asks angular to replace the text content of this
- * HTML element with the value of the given expression, and to keep the text
- * content up to date when the expression's value changes. Usually you would
- * just write `{{ expression }}` and let angular compile it into
+ * The `ng:bind` attribute tells Angular to replace the text content of the specified
+ * HTML element with the value of the given expression, and to update the text
+ * content whenever the expression's value changes. Usually, you would
+ * just write `{{ expression }}` and let Angular compile it into
  * `<span ng:bind="expression"></span>` at bootstrap time.
  *
  * @element ANY
- * @param {expression} expression {@link guide/dev_guide.expressions Expression} to eval.
+ * @param {expression} expression {@link guide/dev_guide.expressions Expression} to evaluate.
  *
  * @example
- * You can try it right here: enter text in the text box and watch the greeting change.
+ * Enter a name in the Live Preview text box and watch the greeting below it change instantly.
    <doc:example>
      <doc:source>
        Enter name: <input type="text" name="name" value="Whirled"> <br>
@@ -227,8 +233,8 @@ angularDirective("ng:bind", function(expression, element){
           delete scope.$element;
         }
       }
-      // If we are HTML than save the raw HTML data so that we don't
-      // recompute sanitization since it is expensive.
+      // If we are HTML, then save the raw HTML data so that we don't
+      // recompute sanitization since that is expensive.
       // TODO: turn this into a more generic way to compute this
       if ((isHtml = (value instanceof HTML)))
         value = (html = value).html;
@@ -458,7 +464,8 @@ angularDirective("ng:bind-attr", function(expression){
  * element is clicked.
  *
  * @element ANY
- * @param {expression} expression {@link guide/dev_guide.expressions Expression} to eval upon click.
+ * @param {expression} expression {@link guide/dev_guide.expressions Expression} to evaluate upon
+ * click.
  *
  * @example
    <doc:example>