docs(API): various api doc fixes from Toni

6 files changed, 106 insertions, 126 deletions

diff --git a/src/Angular.js b/src/Angular.js
index 69d52a2a..d5d862e0 100644
--- a/src/Angular.js
+++ b/src/Angular.js
@@ -6,26 +6,24 @@ if (typeof document.getAttribute == $undefined)
   document.getAttribute = function() {};
 
 /**
- * @workInProgress
  * @ngdoc function
  * @name angular.lowercase
  * @function
  *
- * @description Converts string to lowercase
- * @param {string} string String to be lowercased.
+ * @description Converts the specified string to lowercase.
+ * @param {string} string String to be converted to lowercase.
  * @returns {string} Lowercased string.
  */
 var lowercase = function (string){ return isString(string) ? string.toLowerCase() : string; };
 
 
 /**
- * @workInProgress
  * @ngdoc function
  * @name angular.uppercase
  * @function
  *
- * @description Converts string to uppercase.
- * @param {string} string String to be uppercased.
+ * @description Converts the specified string to uppercase.
+ * @param {string} string String to be converted to uppercase.
  * @returns {string} Uppercased string.
  */
 var uppercase = function (string){ return isString(string) ? string.toUpperCase() : string; };
@@ -112,17 +110,15 @@ var _undefined        = undefined,
     DATE_ISOSTRING_LN = 24;
 
 /**
- * @workInProgress
  * @ngdoc function
  * @name angular.forEach
  * @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, which can be either 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. Specifying a `context` for the function is optional.
  *
  * Note: this function was previously known as `angular.foreach`.
  *
@@ -137,7 +133,7 @@ var _undefined        = undefined,
  *
  * @param {Object|Array} obj Object to iterate over.
  * @param {function()} iterator Iterator function.
- * @param {Object} context Object to become context (`this`) for the iterator function.
+ * @param {Object=} context Object to become context (`this`) for the iterator function.
  * @returns {Object|Array} Reference to `obj`.
  */
 function forEach(obj, iterator, context) {
@@ -217,7 +213,6 @@ function nextUid() {
 }
 
 /**
- * @workInProgress
  * @ngdoc function
  * @name angular.extend
  * @function
@@ -226,8 +221,8 @@ function nextUid() {
  * 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).
+ * @param {Object} dst Destination object.
+ * @param {...Object} src Source object(s).
  */
 function extend(dst) {
   forEach(arguments, function(obj){
@@ -247,14 +242,13 @@ function inherit(parent, extra) {
 
 
 /**
- * @workInProgress
  * @ngdoc function
  * @name angular.noop
  * @function
  *
  * @description
- * Empty function that performs no operation whatsoever. This function is useful when writing code
- * in the functional style.
+ * A function that performs no operations. This function can be useful when writing code in the
+ * functional style.
    <pre>
      function foo(callback) {
        var result = calculateResult();
@@ -266,14 +260,13 @@ function noop() {}
 
 
 /**
- * @workInProgress
  * @ngdoc function
  * @name angular.identity
  * @function
  *
  * @description
- * A function that does nothing except for returning its first argument. This function is useful
- * when writing code in the functional style.
+ * A function that returns its first argument. This function is useful when writing code in the
+ * functional style.
  *
    <pre>
      function transformer(transformationFn, value) {
@@ -298,13 +291,12 @@ function extensionMap(angular, name, transform) {
 }
 
 /**
- * @workInProgress
  * @ngdoc function
  * @name angular.isUndefined
  * @function
  *
  * @description
- * Checks if a reference is undefined.
+ * Determines if a reference is undefined.
  *
  * @param {*} value Reference to check.
  * @returns {boolean} True if `value` is undefined.
@@ -313,13 +305,12 @@ function isUndefined(value){ return typeof value == $undefined; }
 
 
 /**
- * @workInProgress
  * @ngdoc function
  * @name angular.isDefined
  * @function
  *
  * @description
- * Checks if a reference is defined.
+ * Determines if a reference is defined.
  *
  * @param {*} value Reference to check.
  * @returns {boolean} True if `value` is defined.
@@ -328,14 +319,13 @@ function isDefined(value){ return typeof value != $undefined; }
 
 
 /**
- * @workInProgress
  * @ngdoc function
  * @name angular.isObject
  * @function
  *
  * @description
- * Checks if a reference is an `Object`. Unlike in JavaScript `null`s are not considered to be
- * objects.
+ * Determines if a reference is an `Object`. Unlike `typeof` in JavaScript, `null`s are not
+ * considered to be objects.
  *
  * @param {*} value Reference to check.
  * @returns {boolean} True if `value` is an `Object` but not `null`.
@@ -344,13 +334,12 @@ function isObject(value){ return value!=null && typeof value == $object;}
 
 
 /**
- * @workInProgress
  * @ngdoc function
  * @name angular.isString
  * @function
  *
  * @description
- * Checks if a reference is a `String`.
+ * Determines if a reference is a `String`.
  *
  * @param {*} value Reference to check.
  * @returns {boolean} True if `value` is a `String`.
@@ -359,13 +348,12 @@ function isString(value){ return typeof value == $string;}
 
 
 /**
- * @workInProgress
  * @ngdoc function
  * @name angular.isNumber
  * @function
  *
  * @description
- * Checks if a reference is a `Number`.
+ * Determines if a reference is a `Number`.
  *
  * @param {*} value Reference to check.
  * @returns {boolean} True if `value` is a `Number`.
@@ -374,13 +362,12 @@ function isNumber(value){ return typeof value == $number;}
 
 
 /**
- * @workInProgress
  * @ngdoc function
  * @name angular.isDate
  * @function
  *
  * @description
- * Checks if value is a date.
+ * Determines if a value is a date.
  *
  * @param {*} value Reference to check.
  * @returns {boolean} True if `value` is a `Date`.
@@ -389,13 +376,12 @@ function isDate(value){ return value instanceof Date; }
 
 
 /**
- * @workInProgress
  * @ngdoc function
  * @name angular.isArray
  * @function
  *
  * @description
- * Checks if a reference is an `Array`.
+ * Determines if a reference is an `Array`.
  *
  * @param {*} value Reference to check.
  * @returns {boolean} True if `value` is an `Array`.
@@ -404,13 +390,12 @@ function isArray(value) { return value instanceof Array; }
 
 
 /**
- * @workInProgress
  * @ngdoc function
  * @name angular.isFunction
  * @function
  *
  * @description
- * Checks if a reference is a `Function`.
+ * Determines if a reference is a `Function`.
  *
  * @param {*} value Reference to check.
  * @returns {boolean} True if `value` is a `Function`.
@@ -516,7 +501,7 @@ function map(obj, iterator, context) {
  *
  * @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.
+ * @returns {number} The size of `obj` or `0` if `obj` is neither an object nor an array.
  *
  * @example
  * <doc:example>
@@ -583,7 +568,6 @@ function isLeafNode (node) {
 }
 
 /**
- * @workInProgress
  * @ngdoc function
  * @name angular.copy
  * @function
@@ -814,17 +798,14 @@ function sliceArgs(args, startIndex) {
 
 
 /**
- * @workInProgress
  * @ngdoc function
  * @name angular.bind
  * @function
  *
  * @description
- * 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).
+ * Returns a function which calls function `fn` bound to `self` (`self` becomes the `this` for
+ * `fn`). You can supply optional `args` that are are prebound to the function. This feature is also
+ * known as [function currying](http://en.wikipedia.org/wiki/Currying).
  *
  * @param {Object} self Context which `fn` should be evaluated in.
  * @param {function()} fn Function to be bound.
@@ -846,8 +827,7 @@ 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 so they cannot be bound (note: they don't need to be)
     return fn;
   }
 }
@@ -1034,14 +1014,14 @@ function assertArgFn(arg, name) {
  * @ngdoc property
  * @name angular.version
  * @description
- * Object which contains information about the current AngularJS version. The object has following
- * properties:
+ * An object that contains information about the current AngularJS version. This object has the
+ * following properties:
  *
- * - `full` – `{string}` – full version string, e.g. "0.9.18"
- * - `major` – `{number}` – major version number, e.g. 0
- * - `minor` – `{number}` – minor version number, e.g. 9
- * - `dot` – `{number}` – dot version number, e.g. 18
- * - `codeName` – `{string}` – code name of the release, e.g. "jiggling-armfat"
+ * - `full` – `{string}` – Full version string, such as "0.9.18".
+ * - `major` – `{number}` – Major version number, such as "0".
+ * - `minor` – `{number}` – Minor version number, such as "9".
+ * - `dot` – `{number}` – Dot version number, such as "18".
+ * - `codeName` – `{string}` – Code name of the release, such as "jiggling-armfat".
  */
 var version = {
   full: '"NG_VERSION_FULL"',    // all of these placeholder strings will be replaced by rake's
diff --git a/src/Injector.js b/src/Injector.js
index d2bafcf5..912e911c 100644
--- a/src/Injector.js
+++ b/src/Injector.js
@@ -10,11 +10,12 @@
  * dependency injection (see {@link guide/dev_guide.di dependency injection}).
  *
  * Angular creates an injector automatically for the root scope and it is available as the
- * {@link angular.scope.$service $service} property. Creation of the injector automatically creates
- * all of the `$eager` {@link angular.service services}.
+ * {@link angular.scope.$service $service} property. Creating an injector doesn't automatically
+ * create all of the `$eager` {@link angular.service services}. You have to call `injector.eager()`
+ * to initialize them.
  *
- * @param {Object=} [factoryScope={}] `this` for the service factory function.
- * @param {Object.<string, function()>=} [factories=angular.service] Map of service factory
+ * @param {Object=} [factoryScope={}] The `this` for the service factory function.
+ * @param {Object.<string, function()>=} [factories=angular.service] Map of the service factory
  *     functions.
  * @param {Object.<string, function()>=} [instanceCache={}] Place where instances of services are
  *     saved for reuse. Can also be used to override services specified by `serviceFactory`
@@ -22,19 +23,19 @@
  * @returns {function()} Injector function:
  *
  *   * `injector(serviceName)`:
- *     * `serviceName` - `{string=}` - name of the service to retrieve.
+ *     * `serviceName` - `{string=}` - Name of the service to retrieve.
  *
  * The injector function also has these properties:
  *
- *   * an `invoke` property which can be used to invoke methods with dependency-injected arguments.
+ *   * An `invoke` property which can be used to invoke methods with dependency-injected arguments.
  *    `injector.invoke(self, fn, curryArgs)`
- *     * `self` -  "`this`" to be used when invoking the function.
- *     * `fn` - the function to be invoked. The function may have the `$inject` property which
- *        lists the set of arguments which should be auto injected
+ *     * `self` -  The "`this`" to be used when invoking the function.
+ *     * `fn` - The function to be invoked. The function may have the `$inject` property that
+ *        lists the set of arguments which should be auto-injected.
  *        (see {@link guide/dev_guide.di dependency injection}).
- *     * `curryArgs(array)` - optional array of arguments to pass to function invocation after the
- *        injection arguments (also known as curry arguments or currying).
- *   * an `eager` property which is used to initialize the eager services.
+ *     * `curryArgs(array)` - Optional array of arguments to pass to the function
+ *        invocation after the injection arguments (also known as curry arguments or currying).
+ *   * An `eager` property which is used to initialize the eager services.
  *     `injector.eager()`
  */
 function createInjector(factoryScope, factories, instanceCache) {
diff --git a/src/JSON.js b/src/JSON.js
index 34bcfd51..1dc5cc03 100644
--- a/src/JSON.js
+++ b/src/JSON.js
@@ -3,15 +3,14 @@
 var array = [].constructor;
 
 /**
- * @workInProgress
  * @ngdoc function
  * @name angular.toJson
  * @function
  *
  * @description
- * Serializes the input into a JSON formated string.
+ * Serializes input into a JSON-formatted string.
  *
- * @param {Object|Array|Date|string|number} obj Input to jsonify.
+ * @param {Object|Array|Date|string|number} obj Input to be serialized into JSON.
  * @param {boolean=} pretty If set to true, the JSON output will contain newlines and whitespace.
  * @returns {string} Jsonified string representing `obj`.
  */
@@ -22,16 +21,15 @@ function toJson(obj, pretty) {
 }
 
 /**
- * @workInProgress
  * @ngdoc function
  * @name angular.fromJson
  * @function
  *
  * @description
- * Deserializes a string in the JSON format.
+ * Deserializes a JSON string.
  *
  * @param {string} json JSON string to deserialize.
- * @param {boolean} [useNative=false] Use native JSON parser if available
+ * @param {boolean} [useNative=false] Use native JSON parser, if available.
  * @returns {Object|Array|Date|string|number} Deserialized thingy.
  */
 function fromJson(json, useNative) {
diff --git a/src/directives.js b/src/directives.js
index e0ac6c39..b3584a37 100644
--- a/src/directives.js
+++ b/src/directives.js
@@ -184,17 +184,19 @@ angularDirective("ng:controller", function(expression){
  * @name angular.directive.ng:bind
  *
  * @description
- * 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.
+ * The `ng:bind` attribute tells Angular to replace the text content of the specified HTML element
+ * with the value of a given expression, and to update the text content when the value of that
+ * expression changes.
+ *
+ * Typically, you don't use `ng:bind` directly, but instead you use the double curly markup like
+ * `{{ expression }}` and let the Angular compiler transform it to
+ * `<span ng:bind="expression"></span>` when the template is compiled.
  *
  * @element ANY
  * @param {expression} expression {@link guide/dev_guide.expressions Expression} to evaluate.
  *
  * @example
- * Enter a name in the Live Preview text box and watch the greeting below it change instantly.
+ * Enter a name in the Live Preview text box; the greeting below the text box changes instantly.
    <doc:example>
      <doc:source>
        Enter name: <input type="text" name="name" value="Whirled"> <br>
@@ -372,42 +374,40 @@ var REMOVE_ATTRIBUTES = {
   'multiple':'multiple'
 };
 /**
- * @workInProgress
  * @ngdoc directive
  * @name angular.directive.ng:bind-attr
  *
  * @description
- * The `ng:bind-attr` attribute specifies that
- * {@link guide/dev_guide.templates.databinding databindings}  should be created between element
- * attributes and given expressions. Unlike `ng:bind` the `ng:bind-attr` contains a JSON key value
- * pairs representing which attributes need to be mapped to which
- * {@link guide/dev_guide.expressions expressions}.
- *
- * You don't usually write the `ng:bind-attr` in the HTML since embedding
- * <tt ng:non-bindable>{{expression}}</tt> into the attribute directly as the attribute value is
- * preferred. The attributes get translated into `<span ng:bind-attr="{attr:expression}"/>` at
- * compile time.
- *
- * This HTML snippet is preferred way of working with `ng:bind-attr`
+ * The `ng:bind-attr` attribute specifies that a
+ * {@link guide/dev_guide.templates.databinding databinding}  should be created between a particular
+ * element attribute and a given expression. Unlike `ng:bind`, the `ng:bind-attr` contains one or
+ * more JSON key value pairs; each pair specifies an attribute and the
+ * {@link guide/dev_guide.expressions expression} to which it will be mapped.
+ *
+ * Instead of writing `ng:bind-attr` statements in your HTML, you can use double-curly markup to
+ * specify an <tt ng:non-bindable>{{expression}}</tt> for the value of an attribute.
+ * At compile time, the attribute is translated into an `<span ng:bind-attr="{attr:expression}"/>`
+ *
+ * The following HTML snippet shows how to specify `ng:bind-attr`:
  * <pre>
  *   <a href="http://www.google.com/search?q={{query}}">Google</a>
  * </pre>
  *
- * The above gets translated to bellow during bootstrap time.
+ * During compilation, the snippet gets translated to the following:
  * <pre>
  *   <a ng:bind-attr='{"href":"http://www.google.com/search?q={{query}}"}'>Google</a>
  * </pre>
  *
  * @element ANY
- * @param {string} attribute_json a JSON key-value pairs representing
- *    the attributes to replace. Each key matches the attribute
+ * @param {string} attribute_json one or more JSON key-value pairs representing
+ *    the attributes to replace with expressions. Each key matches an attribute
  *    which needs to be replaced. Each value is a text template of
- *    the attribute with embedded
+ *    the attribute with the embedded
  *    <tt ng:non-bindable>{{expression}}</tt>s. Any number of
  *    key-value pairs can be specified.
  *
  * @example
- * Try it here: enter text in text box and click Google.
+ * Enter a search string in the Live Preview text box and then click "Google". The search executes instantly.
    <doc:example>
      <doc:source>
       Google for:
diff --git a/src/jqLite.js b/src/jqLite.js
index 13ba5fd6..cb761294 100644
--- a/src/jqLite.js
+++ b/src/jqLite.js
@@ -5,28 +5,28 @@
 //////////////////////////////////
 
 /**
- * @workInProgress
  * @ngdoc function
  * @name angular.element
  * @function
  *
  * @description
- * Wraps a raw DOM element or HTML string as [jQuery](http://jquery.com) element.
- * `angular.element` is either an alias for [jQuery](http://api.jquery.com/jQuery/) function if
- * jQuery is loaded or a function that wraps the element or string in angular's jQuery lite
- * implementation.
+ * Wraps a raw DOM element or HTML string as a [jQuery](http://jquery.com) element.
+ * `angular.element` can be either an alias for [jQuery](http://api.jquery.com/jQuery/) function, if
+ * jQuery is available, or a function that wraps the element or string in Angular's jQuery lite
+ * implementation (commonly referred to as jqLite).
  *
- * Real jQuery always takes precedence (as long as it was loaded before `DOMContentEvent`)
+ * Real jQuery always takes precedence over jqLite, provided it was loaded before `DOMContentLoaded`
+ * event fired.
  *
- * Angular's jQuery lite implementation is a tiny API-compatible subset of jQuery which allows
- * angular to manipulate DOM. The jQuery lite implements only a subset of jQuery api, with the
- * focus on the most commonly needed functionality and minimal footprint. For this reason only a
- * limited number of jQuery methods, arguments and invocation styles are supported.
+ * jqLite is a tiny, API-compatible subset of jQuery that allows
+ * Angular to manipulate the DOM. jqLite implements only the most commonly needed functionality
+ * within a very small footprint, so only a subset of the jQuery API - methods, arguments and
+ * invocation styles - are supported.
  *
- * Note: All element references in angular are always wrapped with jQuery (lite) and are never
+ * Note: All element references in Angular are always wrapped with jQuery or jqLite; they are never
  * raw DOM references.
  *
- * ## Angular's jQuery lite implements these functions:
+ * ## Angular's jQuery lite provides the following methods:
  *
  * - [addClass()](http://api.jquery.com/addClass/)
  * - [after()](http://api.jquery.com/after/)
@@ -48,10 +48,9 @@
  * - [trigger()](http://api.jquery.com/trigger/)
  * - [eq()](http://api.jquery.com/eq/)
  *
- * ## Additionally these methods extend the jQuery and  are available in both jQuery and jQuery lite
- * version:
+ * ## In addtion to the above, Angular privides an additional method to both jQuery and jQuery lite:
  *
- *- `scope()` - retrieves the current angular scope of the element.
+ * - `scope()` - retrieves the current Angular scope of the element.
  *
  * @param {string|DOMElement} element HTML string or DOMElement to be wrapped into jQuery.
  * @returns {Object} jQuery object.
diff --git a/src/markups.js b/src/markups.js
index 3144bbb0..933d91f4 100644
--- a/src/markups.js
+++ b/src/markups.js
@@ -1,18 +1,17 @@
 'use strict';
 
 /**
- * @workInProgress
  * @ngdoc overview
  * @name angular.markup
  * @description
  *
- * Angular markup transforms content of DOM elements or portions of this content into other text or
- * DOM elements for further compilation.
+ * Angular markup transforms the content of DOM elements or portions of the content into other
+ * text or DOM elements for further compilation.
  *
  * Markup extensions do not themselves produce linking functions. Think of markup as a way to
  * produce shorthand for a {@link angular.widget widget} or a {@link angular.directive directive}.
  *
- * The most prominent example of a markup in angular is the built-in double curly markup
+ * The most prominent example of a markup in Angular is the built-in, double curly markup
  * `{{expression}}`, which is shorthand for `<span ng:bind="expression"></span>`.
  *
  * Create custom markup like this:
@@ -23,21 +22,24 @@
  *   });
  * </pre>
  *
- * For more information about angular markup, see {@link guide/dev_guide.compiler.markup
- * Understanding Angular Markup} in the angular Developer Guide.
+ * For more information, see {@link guide/dev_guide.compiler.markup Understanding Angular Markup}
+ * in the Angular Developer Guide.
  */
 
 /**
- * @workInProgress
  * @ngdoc overview
  * @name angular.attrMarkup
  * @description
  *
- * Attribute markup extends the angular compiler in a very similar way as {@link angular.markup}
- * except that it allows you to modify the state of the attribute text rather than the content of a
- * node.
+ * Attribute markup allows you to modify the state of an attribute's text.
+ *
+ * Attribute markup extends the Angular complier in a way similar to {@link angular.markup},
+ * which allows you to modify the content of a node.
+ *
+ * The most prominent example of an attribute markup in Angular is the built-in double curly markup
+ * which is a shorthand for {@link angular.directive.ng:bind-attr ng:bind-attr}.
  *
- * Create custom attribute markup like this:
+ * ## Example
  *
  * <pre>
  *   angular.attrMarkup('newAttrMarkup', function(attrValue, attrName, element){
@@ -45,8 +47,8 @@
  *   });
  * </pre>
  *
- * For more information about angular attribute markup, see {@link guide/dev_guide.compiler.markup
- * Understanding Angular Markup} in the angular Developer Guide.
+ * For more information about Angular attribute markup, see {@link guide/dev_guide.compiler.markup
+ * Understanding Angular Markup} in the Angular Developer Guide.
  */
 
 function parseBindings(string) {