docs/content/error/$resource/badcfg.ngdoc

@@ -3,7 +3,7 @@
 @fullName Response does not match configured parameter
 @description
 
-This error occurs when the {@link ngResource.$resource `$resource`} service expects a response that can be deserialized as an array, receives an object, or vice versa.
+This error occurs when the {@link ngResource.$resource `$resource`} service expects a response that can be deserialized as an array but receives an object, or vice versa.
 By default, all resource actions expect objects, except `query` which expects arrays.
 
 To resolve this error, make sure your `$resource` configuration matches the actual format of the data returned from the server.

docs/content/guide/e2e-testing.ngdoc

@@ -6,15 +6,15 @@
 # E2E Testing
 
 <div class="alert alert-danger">
-**Note:** In the past, end to end testing could be done with a deprecated tool called
+**Note:** In the past, end-to-end testing could be done with a deprecated tool called
 [Angular Scenario Runner](http://code.angularjs.org/1.2.16/docs/guide/e2e-testing). That tool
 is now in maintenance mode.
 </div>
 
 As applications grow in size and complexity, it becomes unrealistic to rely on manual testing to
 verify the correctness of new features, catch bugs and notice regressions. Unit tests
 are the first line of defense for catching bugs, but sometimes issues come up with integration
-between components which can't be captured in a unit test. End to end tests are made to find
+between components which can't be captured in a unit test. End-to-end tests are made to find
 these problems.
 
 We have built [Protractor](https://github.com/angular/protractor), an end
@@ -23,7 +23,7 @@ Angular application.
 
 ## Using Protractor
 
-Protractor is a [Node.js](http://nodejs.org) program, and runs end to end tests that are also
+Protractor is a [Node.js](http://nodejs.org) program, and runs end-to-end tests that are also
 written in JavaScript and run with node. Protractor uses [WebDriver](https://code.google.com/p/selenium/wiki/GettingStarted)
 to control browsers and simulate user actions.
 
@@ -77,7 +77,7 @@ filter the list of items.
 ## Example
 See the [angular-seed](https://github.com/angular/angular-seed) project for more examples, or look
 at the embedded examples in the Angular documentation (For example, {@link $http $http}
-has an end to end test in the example under the `protractor.js` tag).
+has an end-to-end test in the example under the `protractor.js` tag).
 
 ## Caveats
 

docs/content/guide/expression.ngdoc

@@ -26,8 +26,16 @@ Angular expressions are like JavaScript expressions with the following differenc
   * **Forgiving:** In JavaScript, trying to evaluate undefined properties generates `ReferenceError`
     or `TypeError`. In Angular, expression evaluation is forgiving to `undefined` and `null`.
 
-  * **No Control Flow Statements:** you cannot use the following in an Angular expression:
+  * **No Control Flow Statements:** You cannot use the following in an Angular expression:
     conditionals, loops, or exceptions.
+
+  * **No Function Declarations:** You cannot decleare functions in an Angular expression.
+    Even inside `ng-init` directive
+
+  * **No RegExp Creation With Literal Notation:** You cannot create regular expressions 
+    in an Angular expression.
+
+  * **No Comma And Void Operators:** You cannot use `,` or `void` in an Angular expression.
 
   * **Filters:** You can use {@link guide/filter filters} within expressions to format data before
     displaying it.
@@ -164,11 +172,11 @@ expression. The reason behind this is core to the Angular philosophy that applic
 be in controllers, not the views. If you need a real conditional, loop, or to throw from a view
 expression, delegate to a JavaScript method instead.
 
-## No RegExp creation with literal notation
+## No function declarations or RegExp creation with literal notation
 
-You can't create regular expressions from within AngularJS expressions. This is to avoid complex
-model transformation logic inside templates. Such logic is better placed in a controller or in a dedicated
-filter where it can be tested properly.
+You can't declare functions or create regular expressions from within AngularJS expressions. This is
+to avoid complex model transformation logic inside templates. Such logic is better placed in a 
+controller or in a dedicated filter where it can be tested properly.
 
 ## `$event`
 

docs/content/guide/scope.ngdoc

@@ -177,7 +177,7 @@ for example, only a portion of the view needs to be controlled by Angular.
 
 To examine the scope in the debugger:
 
-  1. right click on the element of interest in your browser and select 'inspect element'. You
+  1. Right click on the element of interest in your browser and select 'inspect element'. You
   should see the browser debugger with the element you clicked on highlighted.
 
   2. The debugger allows you to access the currently selected element in the console as `$0`

docs/content/tutorial/step_06.ngdoc

@@ -16,8 +16,8 @@ about the phones in the catalog.
 
 ## Data
 
-Note that the `phones.json` file contains unique ids and image urls for each of the phones. The
-urls point to the `app/img/phones/` directory.
+Note that the `phones.json` file contains unique IDs and image URLs for each of the phones. The
+URLs point to the `app/img/phones/` directory.
 
 __`app/phones/phones.json`__ (sample snippet):
 
@@ -59,7 +59,7 @@ the element attribute.
 We also added phone images next to each record using an image tag with the {@link
 ng.directive:ngSrc ngSrc} directive. That directive prevents the
 browser from treating the Angular `{{ expression }}` markup literally, and initiating a request to
-invalid url `http://localhost:8000/app/{{phone.imageUrl}}`, which it would have done if we had only
+invalid URL `http://localhost:8000/app/{{phone.imageUrl}}`, which it would have done if we had only
 specified an attribute binding in a regular `src` attribute (`<img src="{{phone.imageUrl}}">`).
 Using the `ngSrc` directive prevents the browser from making an http request to an invalid location.
 

src/Angular.js

@@ -401,6 +401,8 @@ noop.$inject = [];
        return (transformationFn || angular.identity)(value);
      };
    ```
+  * @param {*} value to be returned.
+  * @returns {*} the value passed in.
  */
 function identity($) {return $;}
 identity.$inject = [];

src/ng/directive/select.js

@@ -13,14 +13,15 @@ var ngOptionsMinErr = minErr('ngOptions');
  *
  * The `ngOptions` attribute can be used to dynamically generate a list of `<option>`
  * elements for the `<select>` element using the array or object obtained by evaluating the
- * `ngOptions` comprehension_expression.
+ * `ngOptions` comprehension expression.
  *
  * In many cases, `ngRepeat` can be used on `<option>` elements instead of `ngOptions` to achieve a
- * similar result. However, the `ngOptions` provides some benefits such as reducing memory and
+ * similar result. However, `ngOptions` provides some benefits such as reducing memory and
  * increasing speed by not creating a new scope for each repeated instance, as well as providing
- * more flexibility in how the `select`'s model is assigned via `select as`. `ngOptions` should be
- * used when the `select` model needs to be bound to a non-string value. This is because an option
- * element can only be bound to string values at present.
+ * more flexibility in how the `<select>`'s model is assigned via the `select` **`as`** part of the
+ * comprehension expression. `ngOptions` should be used when the `<select>` model needs to be bound
+ *  to a non-string value. This is because an option element can only be bound to string values at
+ * present.
  *
  * When an item in the `<select>` menu is selected, the array element or object property
  * represented by the selected option will be bound to the model identified by the `ngModel`
@@ -35,28 +36,51 @@ var ngOptionsMinErr = minErr('ngOptions');
  * array of objects. See an example [in this jsfiddle](http://jsfiddle.net/qWzTb/).
  * </div>
  *
- * ## `select as`
+ * ## `select` **`as`**
  *
- * Using `select as` will bind the result of the `select as` expression to the model, but
+ * Using `select` **`as`** will bind the result of the `select` expression to the model, but
  * the value of the `<select>` and `<option>` html elements will be either the index (for array data sources)
- * or property name (for object data sources) of the value within the collection. If a `track by` expression
+ * or property name (for object data sources) of the value within the collection. If a **`track by`** expression
  * is used, the result of that expression will be set as the value of the `option` and `select` elements.
  *
- * ### `select as` with `track by`
  *
- * Using `select as` together with `track by` is not recommended. Reasoning:
+ * ### `select` **`as`** and **`track by`**
+ *
+ * <div class="alert alert-warning">
+ * Do not use `select` **`as`** and **`track by`** in the same expression. They are not designed to work together.
+ * </div>
+ *
+ * Consider the following example:
+ *
+ * ```html
+ * <select ng-options="item.subItem as item.label for item in values track by item.id" ng-model="selected">
+ * ```
+ *
+ * ```js
+ * $scope.values = [{
+ *   id: 1,
+ *   label: 'aLabel',
+ *   subItem: { name: 'aSubItem' }
+ * }, {
+ *   id: 2,
+ *   label: 'bLabel',
+ *   subItem: { name: 'bSubItem' }
+ * }];
+ *
+ * $scope.selected = { name: 'aSubItem' };
+ * ```
+ *
+ * With the purpose of preserving the selection, the **`track by`** expression is always applied to the element
+ * of the data source (to `item` in this example). To calculate whether an element is selected, we do the
+ * following:
+ *
+ * 1. Apply **`track by`** to the elements in the array. In the example: `[1, 2]`
+ * 2. Apply **`track by`** to the already selected value in `ngModel`.
+ *    In the example: this is not possible as **`track by`** refers to `item.id`, but the selected
+ *    value from `ngModel` is `{name: 'aSubItem'}`, so the **`track by`** expression is applied to
+ *    a wrong object, the selected element can't be found, `<select>` is always reset to the "not
+ *    selected" option.
  *
- * - Example: &lt;select ng-options="item.subItem as item.label for item in values track by item.id" ng-model="selected"&gt;
- *   values: [{id: 1, label: 'aLabel', subItem: {name: 'aSubItem'}}, {id: 2, label: 'bLabel', subItem: {name: 'bSubItem'}}],
- *   $scope.selected = {name: 'aSubItem'};
- * - track by is always applied to `value`, with the purpose of preserving the selection,
- *   (to `item` in this case)
- * - to calculate whether an item is selected we do the following:
- *   1. apply `track by` to the values in the array, e.g.
- *      In the example: [1,2]
- *   2. apply `track by` to the already selected value in `ngModel`:
- *      In the example: this is not possible, as `track by` refers to `item.id`, but the selected
- *      value from `ngModel` is `{name: aSubItem}`.
  *
  * @param {string} ngModel Assignable angular expression to data-bind to.
  * @param {string=} name Property name of the form under which the control is published.

src/ng/templateRequest.js

@@ -9,7 +9,7 @@ var $compileMinErr = minErr('$compile');
  * @description
  * The `$templateRequest` service downloads the provided template using `$http` and, upon success,
  * stores the contents inside of `$templateCache`. If the HTTP request fails or the response data
- * of the HTTP request is empty then a `$compile` error will be thrown (the exception can be thwarted
+ * of the HTTP request is empty, a `$compile` error will be thrown (the exception can be thwarted
  * by setting the 2nd parameter of the function to true).
  *
  * @param {string} tpl The HTTP request template URL