From 60a69a1f5d504488f22c9267b584d542c73d9bff Mon Sep 17 00:00:00 2001
From: Ryan Hart <ryanhart2@users.noreply.github.com>
Date: Sat, 3 Oct 2015 05:32:24 +0700
Subject: [PATCH] docs(ngOptions): explain using 'select as' and 'track by'
 together

* change warning to indicate that 'select as' and 'track by' can be used together with care
* provide an example that will work and an example that will not work
* provide a simple explanation of why the non-working example does not work
---
 src/ng/directive/ngOptions.js | 27 +++++++++++++--------------
 1 file changed, 13 insertions(+), 14 deletions(-)

diff --git a/src/ng/directive/ngOptions.js b/src/ng/directive/ngOptions.js
index 282dff3aedd2..2cc8a353edca 100644
--- a/src/ng/directive/ngOptions.js
+++ b/src/ng/directive/ngOptions.js
@@ -58,29 +58,28 @@ var ngOptionsMinErr = minErr('ngOptions');
  * ### `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.
+ * Be careful when using `select` **`as`** and **`track by`** in the same expression.
  * </div>
  *
- * Consider the following example:
+ * This will work:
  *
  * ```html
- * <select ng-options="item.subItem as item.label for item in values track by item.id" ng-model="selected"></select>
+ * <select ng-options="item as item.label for item in items track by item.id" ng-model="selected"></select>
  * ```
  *
- * ```js
- * $scope.values = [{
- *   id: 1,
- *   label: 'aLabel',
- *   subItem: { name: 'aSubItem' }
- * }, {
- *   id: 2,
- *   label: 'bLabel',
- *   subItem: { name: 'bSubItem' }
- * }];
+ * This will not work:
  *
- * $scope.selected = { name: 'aSubItem' };
+ * ```html
+ * <select ng-options="item.value as item.label for item in items track by item.id" ng-model="selected"></select>
  * ```
  *
+ * In both examples the **`track by`** expression is applied sucessfully to each `item` in `items`. It is also
+ * applied to the selected value from `ngModel`. In the first example this will be `item`. However, in the
+ * second example, the selected value will be `item.value` causing the **`track by`** expression to evaluate
+ * `item.value.id`. As a result, the selected element is never found and the `<select>` is always reset to
+ * the "not selected" option.
+ *
+ *
  * 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: