var get = Ember.get, set = Ember.set;

DS.ModelArray = Ember.ArrayProxy.extend({
  type: null,
  content: null,
  store: null,

  init: function() {
    set(this, 'modelCache', Ember.A([]));
    this._super();
  },

  replace: function(index, removed, added) {
    added = added.map(function(item) {
      ember_assert("You can only add items of " + (get(this, 'type') && get(this, 'type').toString()) + " to this association.", !get(this, 'type') || (get(this, 'type') === item.constructor));
      return item.get('clientId');
    });

    this._super(index, removed, added);
  },

  arrayDidChange: function(array, index, removed, added) {
    var modelCache = get(this, 'modelCache');
    modelCache.replace(index, 0, Array(added));

    this._super(array, index, removed, added);
  },

  arrayWillChange: function(array, index, removed, added) {
    this._super(array, index, removed, added);

    var modelCache = get(this, 'modelCache');
    modelCache.replace(index, removed);
  },

  objectAtContent: function(index) {
    var modelCache = get(this, 'modelCache');
    var model = modelCache.objectAt(index);

    if (!model) {
      var store = get(this, 'store');
      var content = get(this, 'content');

      var contentObject = content.objectAt(index);

      if (contentObject !== undefined) {
        model = store.findByClientId(get(this, 'type'), contentObject);
        modelCache.replace(index, 1, [model]);
      }
    }

    return model;
  }
});

@@ -36,80 +36,766 @@
 t;%0A%0A
-DS.ModelArray = Ember.ArrayProxy.extend(%7B%0A  type: null,%0A  content: null,
+/**%0A  A model array is an array that contains records of a certain type. The model%0A  array materializes records as needed when they are retrieved for the first%0A  time. You should not create model arrays yourself. Instead, an instance of%0A  DS.ModelArray or its subclasses will be returned by your application's store%0A  in response to queries.%0A*/%0A%0ADS.ModelArray = Ember.ArrayProxy.extend(%7B%0A%0A  /**%0A    The model type contained by this model array.%0A%0A    @type DS.Model%0A  */%0A  type: null,%0A%0A  // The array of client ids backing the model array. When a%0A  // record is requested from the model array, the record%0A  // for the client id at the same index is materialized, if%0A  // necessary, by the store.%0A  content: null,%0A%0A  // The store that created this model array.
 %0A  s
@@ -895,16 +895,73 @@
 ;%0A  %7D,%0A%0A
+  // Overrides Ember.Array's replace method to implement%0A
   replac

Add documentation to ModelArray