Merge pull request #4592 from pangratz/doc-refresh-query

[DOC] Add documentation for query#update() to refresh query

addon/-private/system/record-arrays/adapter-populated-record-array.js

@@ -14,6 +14,33 @@ const { get } = Ember;
   may trigger a search on the server, whose results would be loaded
   into an instance of the `AdapterPopulatedRecordArray`.
 
+  ---
+
+  If you want to update the array and get the latest records from the
+  adapter, you can invoke [`update()`](#method_update):
+
+  Example
+
+  ```javascript
+  // GET /users?isAdmin=true
+  var admins = store.query('user', { isAdmin: true });
+
+  admins.then(function() {
+    console.log(admins.get("length")); // 42
+  });
+
+  // somewhere later in the app code, when new admins have been created
+  // in the meantime
+  //
+  // GET /users?isAdmin=true
+  admins.update().then(function() {
+    admins.get('isUpdating'); // false
+    console.log(admins.get("length")); // 123
+  });
+
+  admins.get('isUpdating'); // true
+  ```
+
   @class AdapterPopulatedRecordArray
   @namespace DS
   @extends DS.RecordArray

addon/-private/system/store.js

@@ -1156,7 +1156,8 @@ Store = Service.extend({
     Parameters: { "ids" => ["1", "2", "3"] }
     ```
 
-    This method returns a promise, which is resolved with a `RecordArray`
+    This method returns a promise, which is resolved with an
+    [`AdapterPopulatedRecordArray`](http://emberjs.com/api/data/classes/DS.AdapterPopulatedRecordArray.html)
     once the server returns.
 
     @since 1.13.0