     })
     @
 
+  ###
+    Given a timestamp, determines if the content should be fetched from the
+    persistence layer.
+
+    @method isExpiredAt
+    @param {Integer} A timestamp
+    @return {Boolean}
+  ###
   isExpiredAt: (timestamp = 0) ->
     return false if get(@, 'is_loading')
     !!(get(@, 'is_stale') or get(@, 'last_fetched_at') <= timestamp)
 
+
+###
+  `EllaSparseArray` provides an array-like structure that can fetch portions of
+  data from a persistence layer on demand.
+
+  @example
+    var sparseArray = EllaSparseArray.create({
+      didRequestLength: function() {
+        var _this = this;
+        store.query('cat', {page: {offset: 0, limit: 1}}).then(function(response) {
+          _this.provideLength(Ember.get(response, 'meta.page.total'));
+        });
+      },
+      didRequestRange: function(range) {
+        var _this = this;
+        store.query('cat', {page: {offset: range.start, limit: range.length}}).then(function(response) {
+          _this.provideLength(Ember.get(response, 'meta.page.total'));
+          _this.provideObjectsInRange(range, response.get('content').mapBy('record'));
+        });
+      }
+    });
+
+  @class EllaSparseArray
+###
 
 EllaSparseArray = Ember.Object.extend Ember.Array,
   init: ->

  ###
  isSparseArrayItem: true #quack like a duck

  last_fetched_at: 0

  time_to_live: DEFAULT_TTL

  is_stale: computed('last_fetched_at', 'time_to_live', {
    get: ->
      (get(@, 'last_fetched_at') + get(@, 'time_to_live')) <= Date.now()
  })

  is_loading: false

  resolve: (value) ->
    setProperties(@, {
      content: value


    @

  ###
    Clear the content from this item and mark it stale.

    @method resetItem
    @chainable
  ###
  resetItem: ->
    setProperties(@, {
      content: null
