From 5b0a772665aafba6aa1b3cf6eba21241ce132678 Mon Sep 17 00:00:00 2001
From: bmac <bmac325@gmail.com>
Date: Wed, 9 Nov 2016 16:57:59 -0500
Subject: [PATCH] Update the API docs for snapshots

---
 .../-private/system/snapshot-record-array.js  | 93 ++++++++++++++++++-
 addon/-private/system/snapshot.js             | 20 ++++
 addon/-private/system/store.js                |  1 -
 3 files changed, 111 insertions(+), 3 deletions(-)

diff --git a/addon/-private/system/snapshot-record-array.js b/addon/-private/system/snapshot-record-array.js
index ac76dd9498b..652f1bd1906 100644
--- a/addon/-private/system/snapshot-record-array.js
+++ b/addon/-private/system/snapshot-record-array.js
@@ -25,36 +25,125 @@ export default function SnapshotRecordArray(recordArray, meta, options = {}) {
     @type {Array}
   */
   this._recordArray = recordArray;
+
   /**
     Number of records in the array
+
+    Example
+
+    ```app/adapters/post.js
+    import DS from 'ember-data'
+
+    export default DS.JSONAPIAdapter.extend({
+      shouldReloadAll(store, snapshotRecordArray) {
+        return !snapshotRecordArray.length;
+      },
+    });
+    ```
+
     @property length
     @type {Number}
   */
   this.length = recordArray.get('length');
+
   /**
     The type of the underlying records for the snapshots in the array, as a DS.Model
     @property type
     @type {DS.Model}
   */
   this.type = recordArray.get('type');
+
   /**
-    Meta object
+    Meta objects for the record array.
+
+    Example
+
+    ```app/adapters/post.js
+    import DS from 'ember-data'
+
+    export default DS.JSONAPIAdapter.extend({
+      shouldReloadAll(store, snapshotRecordArray) {
+        var lastRequestTime = snapshotRecordArray.meta.lastRequestTime;
+        var twentyMinutes = 20 * 60 * 1000;
+        return Date.now() > lastRequestTime + twentyMinutes;
+      },
+    });
+    ```
+
     @property meta
     @type {Object}
   */
   this.meta = meta;
+
   /**
-    A hash of adapter options
+    A hash of adapter options passed into the store method for this request.
+
+    Example
+
+    ```app/adapters/post.js
+    import MyCustomAdapter from './custom-adapter';
+
+    export default MyCustomAdapter.extend({
+      findAll(store, type, sinceToken, snapshotRecordArray) {
+        if (snapshotRecordArray.adapterOptions.subscribe) {
+          // ...
+        }
+        // ...
+      }
+    });
+    ```
+
     @property adapterOptions
     @type {Object}
   */
   this.adapterOptions = options.adapterOptions;
 
+  /**
+    The relationships to include for this request.
+
+    Example
+
+    ```app/adapters/application.js
+    import DS from 'ember-data';
+
+    export default DS.Adapter.extend({
+      findAll(store, type, snapshotRecordArray) {
+        var url = `/${type.modelName}?include=${encodeURIComponent(snapshotRecordArray.include)}`;
+
+        return fetch(url).then((response) => response.json())
+      }
+    });
+
+    @property include
+    @type {String|Array}
+  */
   this.include = options.include;
 }
 
 /**
   Get snapshots of the underlying record array
+
+  Example
+
+  ```app/adapters/post.js
+  import DS from 'ember-data'
+
+  export default DS.JSONAPIAdapter.extend({
+    shouldReloadAll(store, snapshotArray) {
+      var snapshots = snapshotArray.snapshots();
+
+      return snapshots.any(function(ticketSnapshot) {
+        var timeDiff = moment().diff(ticketSnapshot.attr('lastAccessedAt'), 'minutes');
+        if (timeDiff > 20) {
+          return true;
+        } else {
+          return false;
+        }
+      });
+    }
+  });
+  ```
+
   @method snapshots
   @return {Array} Array of snapshots
 */
diff --git a/addon/-private/system/snapshot.js b/addon/-private/system/snapshot.js
index cd206d1ade1..7194e9790ff 100644
--- a/addon/-private/system/snapshot.js
+++ b/addon/-private/system/snapshot.js
@@ -347,6 +347,26 @@ Snapshot.prototype = {
   },
 
   /**
+    Serializes the snapshot using the serializer for the model.
+
+    Example
+
+    ```app/adapters/application.js
+    import DS from 'ember-data';
+
+    export default DS.Adapter.extend({
+      createRecord(store, type, snapshot) {
+        var data = snapshot.serialize({ includeId: true });
+        var url = `/${type.modelName}`;
+
+        return fetch(url, {
+          method: 'POST',
+          body: data,
+        }).then((response) => response.json())
+      }
+    });
+    ```
+
     @method serialize
     @param {Object} options
     @return {Object} an object whose values are primitive JSON values only
diff --git a/addon/-private/system/store.js b/addon/-private/system/store.js
index 3aa87f66e8f..a016cd22d25 100644
--- a/addon/-private/system/store.js
+++ b/addon/-private/system/store.js
@@ -1450,7 +1450,6 @@ Store = Service.extend({
     });
     ```
 
-
     See [peekAll](#method_peekAll) to get an array of current records in the
     store, without waiting until a reload is finished.