Merge pull request emberjs#3713 from bmac/document-updateRecord

Document the return value of DS.Adapter#updateRecord

packages/ember-data/lib/system/adapter.js

@@ -330,6 +330,14 @@ export default Ember.Object.extend({
 
     Serializes the record update and sends it to the server.
 
+    The updateRecord method is expected to return a promise that will
+    resolve with the serialized record. This allows the backend to
+    inform the Ember Data store the current state of this record after
+    the update. If it is not possible to return a serialized record
+    the updateRecord promise can also resolve with `undefined` and the
+    Ember Data store will assume all of the updates were successfully
+    applied on the backend.
+
     Example
 
     ```app/adapters/application.js