sproutcore 1.5.0.pre.5 → 1.5.0.rc.1

data/lib/frameworks/sproutcore/frameworks/runtime/debug/test_suites/array/base.js

@@ -1,7 +1,7 @@
 // ==========================================================================
 // Project:   SproutCore Costello - Property Observing Library
 // Copyright: ©2006-2011 Strobe Inc. and contributors.
-//            Portions ©2008-2010 Apple Inc. All rights reserved.
+//            Portions ©2008-2011 Apple Inc. All rights reserved.
 // License:   Licensed under MIT license (see license.js)
 // ==========================================================================
 

data/lib/frameworks/sproutcore/frameworks/runtime/debug/test_suites/array/indexOf.js

@@ -1,7 +1,7 @@
 // ==========================================================================
 // Project:   SproutCore Costello - Property Observing Library
 // Copyright: ©2006-2011 Strobe Inc. and contributors.
-//            Portions ©2008-2010 Apple Inc. All rights reserved.
+//            Portions ©2008-2011 Apple Inc. All rights reserved.
 // License:   Licensed under MIT license (see license.js)
 // ==========================================================================
 

data/lib/frameworks/sproutcore/frameworks/runtime/debug/test_suites/array/insertAt.js

@@ -1,7 +1,7 @@
 // ==========================================================================
 // Project:   SproutCore Costello - Property Observing Library
 // Copyright: ©2006-2011 Strobe Inc. and contributors.
-//            Portions ©2008-2010 Apple Inc. All rights reserved.
+//            Portions ©2008-2011 Apple Inc. All rights reserved.
 // License:   Licensed under MIT license (see license.js)
 // ==========================================================================
 

data/lib/frameworks/sproutcore/frameworks/runtime/debug/test_suites/array/objectAt.js

@@ -1,7 +1,7 @@
 // ==========================================================================
 // Project:   SproutCore Costello - Property Observing Library
 // Copyright: ©2006-2011 Strobe Inc. and contributors.
-//            Portions ©2008-2010 Apple Inc. All rights reserved.
+//            Portions ©2008-2011 Apple Inc. All rights reserved.
 // License:   Licensed under MIT license (see license.js)
 // ==========================================================================
 

data/lib/frameworks/sproutcore/frameworks/runtime/debug/test_suites/array/popObject.js

@@ -1,7 +1,7 @@
 // ==========================================================================
 // Project:   SproutCore Costello - Property Observing Library
 // Copyright: ©2006-2011 Strobe Inc. and contributors.
-//            Portions ©2008-2010 Apple Inc. All rights reserved.
+//            Portions ©2008-2011 Apple Inc. All rights reserved.
 // License:   Licensed under MIT license (see license.js)
 // ==========================================================================
 

data/lib/frameworks/sproutcore/frameworks/runtime/debug/test_suites/array/pushObject.js

@@ -1,7 +1,7 @@
 // ==========================================================================
 // Project:   SproutCore Costello - Property Observing Library
 // Copyright: ©2006-2011 Strobe Inc. and contributors.
-//            Portions ©2008-2010 Apple Inc. All rights reserved.
+//            Portions ©2008-2011 Apple Inc. All rights reserved.
 // License:   Licensed under MIT license (see license.js)
 // ==========================================================================
 

data/lib/frameworks/sproutcore/frameworks/runtime/debug/test_suites/array/rangeObserver.js

@@ -1,7 +1,7 @@
 // ==========================================================================
 // Project:   SproutCore Costello - Property Observing Library
 // Copyright: ©2006-2011 Strobe Inc. and contributors.
-//            Portions ©2008-2010 Apple Inc. All rights reserved.
+//            Portions ©2008-2011 Apple Inc. All rights reserved.
 // License:   Licensed under MIT license (see license.js)
 // ==========================================================================
 

data/lib/frameworks/sproutcore/frameworks/runtime/debug/test_suites/array/removeAt.js

@@ -1,7 +1,7 @@
 // ==========================================================================
 // Project:   SproutCore Costello - Property Observing Library
 // Copyright: ©2006-2011 Strobe Inc. and contributors.
-//            Portions ©2008-2010 Apple Inc. All rights reserved.
+//            Portions ©2008-2011 Apple Inc. All rights reserved.
 // License:   Licensed under MIT license (see license.js)
 // ==========================================================================
 

data/lib/frameworks/sproutcore/frameworks/runtime/debug/test_suites/array/removeObject.js

@@ -1,7 +1,7 @@
 // ==========================================================================
 // Project:   SproutCore Costello - Property Observing Library
 // Copyright: ©2006-2011 Strobe Inc. and contributors.
-//            Portions ©2008-2010 Apple Inc. All rights reserved.
+//            Portions ©2008-2011 Apple Inc. All rights reserved.
 // License:   Licensed under MIT license (see license.js)
 // ==========================================================================
 

data/lib/frameworks/sproutcore/frameworks/runtime/debug/test_suites/array/replace.js

@@ -1,7 +1,7 @@
 // ==========================================================================
 // Project:   SproutCore Costello - Property Observing Library
 // Copyright: ©2006-2011 Strobe Inc. and contributors.
-//            Portions ©2008-2010 Apple Inc. All rights reserved.
+//            Portions ©2008-2011 Apple Inc. All rights reserved.
 // License:   Licensed under MIT license (see license.js)
 // ==========================================================================
 

data/lib/frameworks/sproutcore/frameworks/runtime/debug/test_suites/array/shiftObject.js

@@ -1,7 +1,7 @@
 // ==========================================================================
 // Project:   SproutCore Costello - Property Observing Library
 // Copyright: ©2006-2011 Strobe Inc. and contributors.
-//            Portions ©2008-2010 Apple Inc. All rights reserved.
+//            Portions ©2008-2011 Apple Inc. All rights reserved.
 // License:   Licensed under MIT license (see license.js)
 // ==========================================================================
 

data/lib/frameworks/sproutcore/frameworks/runtime/debug/test_suites/array/unshiftObject.js

@@ -1,7 +1,7 @@
 // ==========================================================================
 // Project:   SproutCore Costello - Property Observing Library
 // Copyright: ©2006-2011 Strobe Inc. and contributors.
-//            Portions ©2008-2010 Apple Inc. All rights reserved.
+//            Portions ©2008-2011 Apple Inc. All rights reserved.
 // License:   Licensed under MIT license (see license.js)
 // ==========================================================================
 

data/lib/frameworks/sproutcore/frameworks/runtime/license.js

@@ -3,7 +3,7 @@
  * ==========================================================================
  * SproutCore Costello -- Property Observing Library
  * Copyright ©2006-2011, Strobe Inc. and contributors.
- * Portions copyright ©2008-2010 Apple Inc. All rights reserved.
+ * Portions copyright ©2008-2011 Apple Inc. All rights reserved.
  * 
  * Permission is hereby granted, free of charge, to any person obtaining a 
  * copy of this software and associated documentation files (the "Software"), 

data/lib/frameworks/sproutcore/frameworks/runtime/mixins/array.js

@@ -1,7 +1,7 @@
 // ==========================================================================
 // Project:   SproutCore Costello - Property Observing Library
 // Copyright: ©2006-2011 Strobe Inc. and contributors.
-//            Portions ©2008-2010 Apple Inc. All rights reserved.
+//            Portions ©2008-2011 Apple Inc. All rights reserved.
 // License:   Licensed under MIT license (see license.js)
 // ==========================================================================
 
@@ -45,10 +45,11 @@ SC.OUT_OF_RANGE_EXCEPTION = "Index out of range" ;
   @extends SC.Enumerable
   @since SproutCore 0.9.0
 */
-SC.Array = {
+SC.Array = /** @scope SC.Array.prototype */{
 
   /**
     Walk like a duck - use isSCArray to avoid conflicts
+    @type Boolean
   */
   isSCArray: YES,
 
@@ -65,6 +66,9 @@ SC.Array = {
     should replace amt objects started at idx with the objects in the passed
     array.  You should also call this.enumerableContentDidChange() ;
 
+    NOTE: JavaScript arrays already implement SC.Array and 
+    calls this.enumerableContentDidChange.
+
     @param {Number} idx
       Starting index in the array to replace.  If idx >= length, then append to
       the end of the array.
@@ -199,6 +203,10 @@ SC.Array = {
   /**
     Push the object onto the end of the array.  Works just like push() but it
     is KVO-compliant.
+    
+    @param {Object} object the objects to push
+        
+    @return {Object} The passed object
   */
   pushObject: function(obj) {
     this.insertAt(this.get('length'), obj) ;
@@ -223,6 +231,8 @@ SC.Array = {
   /**
     Pop object from array or nil if none are left.  Works just like pop() but
     it is KVO-compliant.
+    
+    @return {Object} The popped object
   */
   popObject: function() {
     var len = this.get('length') ;
@@ -236,6 +246,8 @@ SC.Array = {
   /**
     Shift an object from start of array or nil if none are left.  Works just
     like shift() but it is KVO-compliant.
+        
+    @return {Object} The shifted object
   */
   shiftObject: function() {
     if (this.get('length') === 0) return null ;
@@ -247,6 +259,9 @@ SC.Array = {
   /**
     Unshift an object to start of array.  Works just like unshift() but it is
     KVO-compliant.
+        
+    @param {Object} obj the object to add
+    @return {Object} The passed object
   */
   unshiftObject: function(obj) {
     this.insertAt(0, obj) ;
@@ -269,7 +284,10 @@ SC.Array = {
   },
 
   /**
-    Compares each item in the array.  Returns true if they are equal.
+    Compares each item in the passed array to this one. 
+    
+    @param {Array} ary The array you want to compare to
+    @returns {Boolean} true if they are equal.
   */
   isEqual: function(ary) {
     if (!ary) return false ;
@@ -288,7 +306,7 @@ SC.Array = {
     Generates a new array with the contents of the old array, sans any null
     values.
 
-    @returns {Array}
+    @returns {Array} The new, compact array
   */
   compact: function() { return this.without(null); },
 
@@ -296,8 +314,8 @@ SC.Array = {
     Generates a new array with the contents of the old array, sans the passed
     value.
 
-    @param {Object} value
-    @returns {Array}
+    @param {Object} value The value you want to be removed
+    @returns {Array} The new, filtered array
   */
   without: function(value) {
     if (this.indexOf(value)<0) return this; // value not present.
@@ -312,7 +330,7 @@ SC.Array = {
     Generates a new array with only unique values from the contents of the
     old array.
 
-    @returns {Array}
+    @returns {Array} The new, de-duped array
   */
   uniq: function() {
     var ret = [] ;
@@ -366,9 +384,7 @@ SC.Array = {
 
     The callback for a range observer should have the signature:
 
-    {{{
-      function rangePropertyDidChange(array, objects, key, indexes, context)
-    }}}
+          function rangePropertyDidChange(array, objects, key, indexes, context)
 
     If the passed key is '[]' it means that the object itself changed.
 
@@ -484,10 +500,15 @@ SC.Array = {
       changes.add(start, length);
     }
 
-    this._setupEnumerableObservers(addedObjects, removedObjects);
+    this._setupContentObservers(addedObjects, removedObjects);
     this.notifyPropertyChange('[]') ;
     this.endPropertyChanges();
 
+    // Only notify enumerable observers if we have enough information to do so.
+    if (addedObjects && removedObjects) {
+      this._notifyEnumerableObservers(addedObjects, removedObjects, start);
+    }
+
     return this ;
   },
 
@@ -519,6 +540,9 @@ SC.Array = SC.mixin({}, SC.Enumerable, SC.Array) ;
   Returns a new array that is a slice of the receiver.  This implementation
   uses the observable array methods to retrieve the objects for the new
   slice.
+  
+  If you don't pass in beginIndex and endIndex, it will act as a copy of the
+  array.
 
   @param beginIndex {Integer} (Optional) index to begin slicing from.
   @param endIndex {Integer} (Optional) index to end the slice at.
@@ -605,6 +629,7 @@ if (!Array.prototype.lastIndexOf) {
       // replaced range.  Otherwise, pass the full remaining array length
       // since everything has shifted
       var len = objects ? (objects.get ? objects.get('length') : objects.length) : 0;
+      objects = SC.isArray(objects) ? objects : [objects];
       this.enumerableContentDidChange(idx, amt, len - amt, objects, removedObjects) ;
       return this ;
     },
@@ -621,10 +646,15 @@ if (!Array.prototype.lastIndexOf) {
 
   });
 
-  // If browser did not implement indexOf natively, then override with
-  // specialized version
   var indexOf = Array.prototype.indexOf;
   if (!indexOf || (indexOf === SC.Array.indexOf)) {
+    /**
+      Returns the index for a particular object in the index.
+
+      @param {Object} object the item to search for
+      @param {NUmber} startAt optional starting location to search, default 0
+      @returns {Number} index of -1 if not found
+    */
     Array.prototype.indexOf = function(object, startAt) {
       var idx, len = this.length;
 
@@ -641,6 +671,13 @@ if (!Array.prototype.lastIndexOf) {
 
   var lastIndexOf = Array.prototype.lastIndexOf ;
   if (!lastIndexOf || (lastIndexOf === SC.Array.lastIndexOf)) {
+    /**
+      Returns the last index for a particular object in the index.
+
+      @param {Object} object the item to search for
+      @param {NUmber} startAt optional starting location to search, default 0
+      @returns {Number} index of -1 if not found
+    */
     Array.prototype.lastIndexOf = function(object, startAt) {
       var idx, len = this.length;
 

data/lib/frameworks/sproutcore/frameworks/runtime/mixins/comparable.js

@@ -1,12 +1,12 @@
 // ==========================================================================
 // Project:   SproutCore Costello - Property Observing Library
 // Copyright: ©2006-2011 Strobe Inc. and contributors.
-//            Portions ©2008-2010 Apple Inc. All rights reserved.
+//            Portions ©2008-2011 Apple Inc. All rights reserved.
 // License:   Licensed under MIT license (see license.js)
 // ==========================================================================
 
 /**
-  @namespace
+  @class
 
   Implements some standard methods for comparing objects. Add this mixin to
   any class you create that can compare its instances.
@@ -27,12 +27,15 @@ SC.Comparable = {
   /**
     Override to return the result of the comparison of the two parameters. The
     compare method should return
+    
+    <pre>
       -1 if a < b
        0 if a == b
        1 if a > b
+    </pre>
 
-    Default implementation raises
-    an exception.
+
+    Default implementation raises an exception.
 
     @param a {Object} the first object to compare
     @param b {Object} the second object to compare

data/lib/frameworks/sproutcore/frameworks/runtime/mixins/copyable.js

@@ -1,12 +1,12 @@
 // ==========================================================================
 // Project:   SproutCore Costello - Property Observing Library
 // Copyright: ©2006-2011 Strobe Inc. and contributors.
-//            Portions ©2008-2010 Apple Inc. All rights reserved.
+//            Portions ©2008-2011 Apple Inc. All rights reserved.
 // License:   Licensed under MIT license (see license.js)
 // ==========================================================================
 
 /**
-  @namespace
+  @class
 
   Impelements some standard methods for copying an object.  Add this mixin to
   any object you create that can create a copy of itself.  This mixin is
@@ -19,7 +19,7 @@
 
   @since SproutCore 1.0
 */
-SC.Copyable = {
+SC.Copyable = /** @scope SC.Copyable.prototype */{
 
   /**
     Walk like a duck.  Indicates that the object can be copied.
@@ -62,6 +62,13 @@ SC.Copyable = {
 
 // Make Array copyable
 SC.mixin(Array.prototype, SC.Copyable);
+/**
+  Override to return a copy of the receiver.  Default implementation raises
+  an exception.
+
+  @param deep {Boolean} if true, a deep copy of the object should be made
+  @returns {Object} copy of receiver
+*/
 Array.prototype.copy = function(deep) {
 	var ret = this.slice(), idx;
 	if (deep) {

data/lib/frameworks/sproutcore/frameworks/runtime/mixins/enumerable.js

@@ -1,7 +1,7 @@
 // ==========================================================================
 // Project:   SproutCore Costello - Property Observing Library
 // Copyright: ©2006-2011 Strobe Inc. and contributors.
-//            Portions ©2008-2010 Apple Inc. All rights reserved.
+//            Portions ©2008-2011 Apple Inc. All rights reserved.
 // License:   Licensed under MIT license (see license.js)
 // ==========================================================================
 
@@ -11,7 +11,7 @@ sc_require('system/enumerator');
 /*globals Prototype */
 
 /**
-  @namespace
+  @class
 
   This mixin defines the common interface implemented by enumerable objects
   in SproutCore.  Most of these methods follow the standard Array iteration
@@ -22,7 +22,8 @@ sc_require('system/enumerator');
   can use any of these methods on simple arrays.  If Array already implements
   one of these methods, the mixin will not override them.
 
-  h3. Writing Your Own Enumerable
+  Writing Your Own Enumerable
+  -----
 
   To make your own custom class enumerable, you need two items:
 
@@ -33,11 +34,12 @@ sc_require('system/enumerator');
 
   2. If you must implement nextObject().  See documentation.
 
-  Once you have these two methods implement, apply the SC.Enumerable mixin
+  Once you have these two methods implemented, apply the SC.Enumerable mixin
   to your class and you will be able to enumerate the contents of your object
   like any other collection.
 
-  h3. Using SproutCore Enumeration with Other Libraries
+  Using SproutCore Enumeration with Other Libraries
+  -----
 
   Many other libraries provide some kind of iterator or enumeration like
   facility.  This is often where the most common API conflicts occur.
@@ -47,12 +49,12 @@ sc_require('system/enumerator');
 
   @since SproutCore 1.0
 */
-SC.Enumerable = {
+SC.Enumerable = /** @scope SC.Enumerable.prototype */{
 
   /**
     Walk like a duck.
 
-    @property {Boolean}
+    @type Boolean
   */
   isEnumerable: YES,
 
@@ -82,9 +84,9 @@ SC.Enumerable = {
     The default impementation of this method simply looks up the index.
     This works great on any Array-like objects.
 
-    @param index {Number} the current index of the iteration
-    @param previousObject {Object} the value returned by the last call to nextObject.
-    @param context {Object} a context object you can use to maintain state.
+    @param {Number} index the current index of the iteration
+    @param {Object} previousObject the value returned by the last call to nextObject.
+    @param {Object} context a context object you can use to maintain state.
     @returns {Object} the next object in the iteration or undefined
   */
   nextObject: function(index, previousObject, context) {
@@ -142,9 +144,7 @@ SC.Enumerable = {
     The callback method you provide should have the following signature (all
     parameters are optional):
 
-    {{{
-      function(item, index, enumerable) ;
-    }}}
+          function(item, index, enumerable) ;
 
     - *item* is the current item in the iteration.
     - *index* is the current index in the iteration
@@ -154,8 +154,8 @@ SC.Enumerable = {
     object that will be set as "this" on the context.  This is a good way
     to give your iterator function access to the current object.
 
-    @params callback {Function} the callback to execute
-    @params target {Object} the target object to use
+    @param {Function} callback the callback to execute
+    @param {Object} target the target object to use
     @returns {Object} this
   */
   forEach: function(callback, target) {
@@ -217,9 +217,7 @@ SC.Enumerable = {
     The callback method you provide should have the following signature (all
     parameters are optional):
 
-    {{{
-      function(item, index, enumerable) ;
-    }}}
+        function(item, index, enumerable) ;
 
     - *item* is the current item in the iteration.
     - *index* is the current index in the iteration
@@ -231,8 +229,8 @@ SC.Enumerable = {
     object that will be set as "this" on the context.  This is a good way
     to give your iterator function access to the current object.
 
-    @params callback {Function} the callback to execute
-    @params target {Object} the target object to use
+    @param {Function} callback the callback to execute
+    @param {Object} target the target object to use
     @returns {Array} The mapped array.
   */
   map: function(callback, target) {
@@ -257,7 +255,7 @@ SC.Enumerable = {
     Similar to map, this specialized function returns the value of the named
     property on all items in the enumeration.
 
-    @params key {String} name of the property
+    @param {String} key name of the property
     @returns {Array} The mapped array.
   */
   mapProperty: function(key) {
@@ -274,9 +272,7 @@ SC.Enumerable = {
     The callback method you provide should have the following signature (all
     parameters are optional):
 
-    {{{
-      function(item, index, enumerable) ;
-    }}}
+          function(item, index, enumerable) ;
 
     - *item* is the current item in the iteration.
     - *index* is the current index in the iteration
@@ -288,8 +284,8 @@ SC.Enumerable = {
     object that will be set as "this" on the context.  This is a good way
     to give your iterator function access to the current object.
 
-    @params callback {Function} the callback to execute
-    @params target {Object} the target object to use
+    @param {Function} callback the callback to execute
+    @param {Object} target the target object to use
     @returns {Array} A filtered array.
   */
   filter: function(callback, target) {
@@ -350,8 +346,8 @@ SC.Enumerable = {
     can pass an optional second argument with the target value.  Otherwise
     this will match any property that evaluates to true.
 
-    @params key {String} the property to test
-    @param value {String} optional value to test against.
+    @param {String} key the property to test
+    @param {String} value optional value to test against.
     @returns {Array} filtered array
   */
   filterProperty: function(key, value) {
@@ -379,9 +375,7 @@ SC.Enumerable = {
     The callback method you provide should have the following signature (all
     parameters are optional):
 
-    {{{
-      function(item, index, enumerable) ;
-    }}}
+          function(item, index, enumerable) ;
 
     - *item* is the current item in the iteration.
     - *index* is the current index in the iteration
@@ -393,8 +387,8 @@ SC.Enumerable = {
     object that will be set as "this" on the context.  This is a good way
     to give your iterator function access to the current object.
 
-    @params callback {Function} the callback to execute
-    @params target {Object} the target object to use
+    @param {Function} callback the callback to execute
+    @param {Object} target the target object to use
     @returns {Object} Found item or null.
   */
   find: function(callback, target) {
@@ -420,8 +414,8 @@ SC.Enumerable = {
 
     This method works much like the more generic find() method.
 
-    @params key {String} the property to test
-    @param value {String} optional value to test against.
+    @param {String} key the property to test
+    @param {String} value optional value to test against.
     @returns {Object} found item or null
   */
   findProperty: function(key, value) {
@@ -447,9 +441,7 @@ SC.Enumerable = {
     The callback method you provide should have the following signature (all
     parameters are optional):
 
-    {{{
-      function(item, index, enumerable) ;
-    }}}
+          function(item, index, enumerable) ;
 
     - *item* is the current item in the iteration.
     - *index* is the current index in the iteration
@@ -461,14 +453,12 @@ SC.Enumerable = {
     object that will be set as "this" on the context.  This is a good way
     to give your iterator function access to the current object.
 
-    h4. Example Usage
+    Example Usage:
 
-    {{{
-      if (people.every(isEngineer)) { Paychecks.addBigBonus(); }
-    }}}
+          if (people.every(isEngineer)) { Paychecks.addBigBonus(); }
 
-    @params callback {Function} the callback to execute
-    @params target {Object} the target object to use
+    @param {Function} callback the callback to execute
+    @param {Object} target the target object to use
     @returns {Boolean}
   */
   every: function(callback, target) {
@@ -493,8 +483,8 @@ SC.Enumerable = {
     Returns YES if the passed property resolves to true for all items in the
     enumerable.  This method is often simpler/faster than using a callback.
 
-    @params key {String} the property to test
-    @param value {String} optional value to test against.
+    @param {String} key the property to test
+    @param {String} value optional value to test against.
     @returns {Array} filtered array
   */
   everyProperty: function(key, value) {
@@ -521,9 +511,7 @@ SC.Enumerable = {
     The callback method you provide should have the following signature (all
     parameters are optional):
 
-    {{{
-      function(item, index, enumerable) ;
-    }}}
+          function(item, index, enumerable) ;
 
     - *item* is the current item in the iteration.
     - *index* is the current index in the iteration
@@ -535,14 +523,12 @@ SC.Enumerable = {
     object that will be set as "this" on the context.  This is a good way
     to give your iterator function access to the current object.
 
-    h4. Usage Example
+    Usage Example:
 
-    {{{
-      if (people.some(isManager)) { Paychecks.addBiggerBonus(); }
-    }}}
+          if (people.some(isManager)) { Paychecks.addBiggerBonus(); }
 
-    @params callback {Function} the callback to execute
-    @params target {Object} the target object to use
+    @param {Function} callback the callback to execute
+    @param {Object} target the target object to use
     @returns {Array} A filtered array.
   */
   some: function(callback, target) {
@@ -567,8 +553,8 @@ SC.Enumerable = {
     Returns YES if the passed property resolves to true for any item in the
     enumerable.  This method is often simpler/faster than using a callback.
 
-    @params key {String} the property to test
-    @param value {String} optional value to test against.
+    @param {String} key the property to test
+    @param {String} value optional value to test against.
     @returns {Boolean} YES
   */
   someProperty: function(key, value) {
@@ -595,9 +581,7 @@ SC.Enumerable = {
     The callback method you provide should have the following signature (all
     parameters are optional):
 
-    {{{
-      function(previousValue, item, index, enumerable) ;
-    }}}
+          function(previousValue, item, index, enumerable) ;
 
     - *previousValue* is the value returned by the last call to the iterator.
     - *item* is the current item in the iteration.
@@ -614,10 +598,10 @@ SC.Enumerable = {
     pass a target object to set as this for the callback.  It's part of the
     spec. Sorry.
 
-    @params callback {Function} the callback to execute
-    @params initialValue {Object} initial value for the reduce
-    @params reducerProperty {String} internal use only.  May not be available.
-    @returns {Array} A filtered array.
+    @param {Function} callback the callback to execute
+    @param {Object} initialValue initial value for the reduce
+    @param {String} reducerProperty internal use only.  May not be available.
+    @returns {Object} The reduced value.
   */
   reduce: function(callback, initialValue, reducerProperty) {
     if (typeof callback !== "function") throw new TypeError() ;
@@ -657,8 +641,8 @@ SC.Enumerable = {
     implements it.  This method corresponds to the implementation in
     Prototype 1.6.
 
-    @param methodName {String} the name of the method
-    @param args {Object...} optional arguments to pass as well.
+    @param {String} methodName the name of the method
+    @param {Object...} args optional arguments to pass as well.
     @returns {Array} return values from calling invoke.
   */
   invoke: function(methodName) {
@@ -695,9 +679,9 @@ SC.Enumerable = {
     a useful way to attempt to apply changes to a collection of objects unless
     or until one fails.
 
-    @param targetValue {Object} the target return value
-    @param methodName {String} the name of the method
-    @param args {Object...} optional arguments to pass as well.
+    @param {Object} targetValue the target return value
+    @param {String} methodName the name of the method
+    @param {Object...} args optional arguments to pass as well.
     @returns {Array} return values from calling invoke.
   */
   invokeWhile: function(targetValue, methodName) {
@@ -745,7 +729,7 @@ SC.Enumerable = {
     Converts an enumerable into a matrix, with inner arrays grouped based
     on a particular property of the elements of the enumerable.
 
-    @params key {String} the property to test
+    @param {String} key the property to test
     @returns {Array} matrix of arrays
   */
   groupBy: function(key){
@@ -753,14 +737,14 @@ SC.Enumerable = {
         ret = [],
         last = null,
         context = SC.Enumerator._popContext(),
-        grouped = [], 
+        grouped = [],
         keyValues = [],
         idx, next, cur;
-    
+
     for(idx=0;idx<len;idx++) {
       next = this.nextObject(idx, last, context) ;
       cur = next ? (next.get ? next.get(key) : next[key]) : null;
-      if(SC.none(grouped[cur])) { 
+      if(SC.none(grouped[cur])) {
         grouped[cur] = []; keyValues.push(cur);
       }
       grouped[cur].push(next);
@@ -768,9 +752,9 @@ SC.Enumerable = {
     }
     last = null;
     context = SC.Enumerator._pushContext(context);
-    
+
     for(idx=0,len=keyValues.length; idx < len; idx++){
-      ret.push(grouped[keyValues[idx]]);        
+      ret.push(grouped[keyValues[idx]]);
     }
     return ret ;
   }
@@ -793,7 +777,8 @@ SC._buildReducerFor = function(reducerKey, reducerProperty) {
   }.property('[]') ;
 };
 
-SC.Reducers = /** @lends SC.Enumerable */ {
+/** @class */
+SC.Reducers = /** @scope SC.Reducers.prototype */ {
   /**
     This property will trigger anytime the enumerable's content changes.
     You can observe this property to be notified of changes to the enumerables
@@ -821,18 +806,258 @@ SC.Reducers = /** @lends SC.Enumerable */ {
     @returns {Object} receiver
   */
   enumerableContentDidChange: function(start, length, delta, addedObjects, removedObjects) {
-    this._setupEnumerableObservers(addedObjects, removedObjects);
+    this._setupContentObservers(addedObjects, removedObjects);
     this.notifyPropertyChange('[]') ;
+    this._notifyEnumerableObservers(addedObjects, removedObjects, start);
+  },
+
+  /**
+    For all registered property chains on this object, removed them from objects
+    being removed from the enumerable, and clone them onto newly added objects.
+
+    @param {Object[]} addedObjects the objects being added to the enumerable
+    @param {Object[]} removedObjects the objected being removed from the enumerable
+    @returns {Object} receiver
+  */
+  setupPropertyChainsForEnumerableContent: function(addedObjects, removedObjects) {
+    var chains = this._kvo_enumerable_property_chains;
+
+    if (chains) {
+      chains.forEach(function(chain) {
+        var idx, len = removedObjects.get('length'),
+            chainGuid = SC.guidFor(chain),
+            clonedChain, item, kvoChainList = '_kvo_enumerable_property_clones';
+
+        chain.notifyPropertyDidChange();
+
+        for (idx = 0; idx < len; idx++) {
+          item = removedObjects[idx];
+          clonedChain = item[kvoChainList][chainGuid];
+          clonedChain.deactivate();
+          delete item[kvoChainList][chainGuid];
+        }
 
+        len = addedObjects.get('length');
+        for (idx = 0; idx < len; idx++) {
+          this._clonePropertyChainToItem(chain, addedObjects[idx]);
+        }
+      }, this);
+    }
     return this ;
   },
 
+  /**
+    Register a property chain to propagate to enumerable content.
+
+    This will clone the property chain to each item in the enumerable,
+    then save it so that it is automatically set up and torn down when
+    the enumerable content changes.
+
+    @param {String} property the property being listened for on this object
+    @param {SC._PropertyChain} chain the chain to clone to items
+  */
+  registerDependentKeyWithChain: function(property, chain) {
+    // Get the set of all existing property chains that should
+    // be propagated to enumerable contents. If that set doesn't
+    // exist yet, _kvo_for() will create it.
+    var kvoChainList = '_kvo_enumerable_property_chains',
+        chains, item, clone, cloneList;
+
+    chains = this._kvo_for(kvoChainList, SC.CoreSet);
+
+    // Save a reference to the chain on this object. If new objects
+    // are added to the enumerable, we will clone this chain and add
+    // it to the new object.
+    chains.add(chain);
+
+    this.forEach(function(item) {
+      this._clonePropertyChainToItem(chain, item);
+    }, this);
+  },
+
+  /**
+    Clones an SC._PropertyChain to a content item.
+
+    @param {SC._PropertyChain} chain
+    @param {Object} item
+  */
+  _clonePropertyChainToItem: function(chain, item) {
+    var clone        = SC.clone(chain),
+        kvoCloneList = '_kvo_enumerable_property_clones',
+        cloneList;
+
+    clone.object = item;
+
+    cloneList = item[kvoCloneList] = item[kvoCloneList] || {};
+    cloneList[SC.guidFor(chain)] = clone;
+
+    clone.activate(item);
+  },
+
+  /**
+    Removes a dependent key from the enumerable, and tears it down on
+    all content objects.
+
+    @param {String} property
+    @param {SC._PropertyChain} chain
+  */
+  removeDependentKeyWithChain: function(property, chain) {
+    var kvoChainList = '_kvo_enumerable_property_chains',
+        kvoCloneList = '_kvo_enumerable_property_clones',
+        chains, item, clone, cloneList;
+
+    this.forEach(function(item) {
+      item.removeDependentKeyWithChain(property, chain);
+
+      cloneList = item[kvoCloneList];
+      clone = cloneList[SC.guidFor(chain)];
+
+      clone.deactivate(item);
+    }, this);
+  },
+
+  /**
+    Called when the contents of the enumerable mutates.
+
+    Implementers of classes that mixin SC.Enumerable should ensure that they
+    call enumerableContentDidChange(), which invokes this method automatically.
+
+    @param {Array} addedObjects the array of objects that were added to the enumerable
+    @param {Array} removedObjects the array of objects that were removed from the enumerable
+    @param {Number} index the index at which the mutation occurred
+  */
+  _notifyEnumerableObservers: function(addedObjects, removedObjects, index) {
+    var observers, members, member, memberLoc, membersLength;
+    var target, method, context;
+
+    observers = this._kvo_enumerable_observers;
+
+    if (observers) {
+      members = SC.clone(observers.getMembers());
+      membersLength = members.length;
+
+      for(memberLoc=0; memberLoc < membersLength; memberLoc++) {
+        member = members[memberLoc];
+
+        target = member[0];
+        method = member[1];
+        context = member[2];
+
+        method.call(target, addedObjects, removedObjects, index, this, context);
+      }
+    }
+  },
+
+  /**
+    Adds an enumerable observer to the enumerable.
+
+    Enumerable observers are called whenever the enumerable's content
+    mutates. For example, adding an object via pushObject(), or replacing
+    objects via replace(), will cause all enumerable observers to be fired.
+
+    Observer methods that you register should have the following signature:
+
+        enumerableDidChange: function(addedObjects, removedObjects, index, source)
+
+    addedObjects will contain an array of the objects added and removedObjects
+    will contain an array of the objects that were removed. The index parameter
+    contains the index at which the mutation occurred.
+
+    The fourth parameter, source, is the enumerable that mutated. This is useful
+    if you register the same observer method on multiple enumerables.
+
+    If you pass a context parameter to addEnumerableObserver(), it will be
+    included when the observer is fired:
+
+        function(addedObjects, removedObjects, sender, context);
+
+    @param {Object} target the target object to invoke
+    @param {String|Function} method the method to invoke
+    @param {Object} context optional context
+
+    @returns {SC.Object} self
+  */
+  addEnumerableObserver: function(target, method, context) {
+    var observers;
+
+    // Normalize parameters. If a function is passed as
+    // target, make it the method.
+    if (method === undefined) {
+      method = target;
+      target = this;
+    }
+
+    // Call the observer in the context of the enumerable
+    // if no explicit target is given.
+    if (!target) { target = this; }
+
+    // If the method is provided as a string, look it up on
+    // the target.
+    if (typeof method === "string") {
+      method = target[method];
+    }
+
+    if (!method) {
+      throw "You must pass a method to addEnumerableObserver()";
+    }
+
+    observers = this._kvo_for('_kvo_enumerable_observers', SC.ObserverSet);
+    observers.add(target, method, context);
+
+    return this;
+  },
+
+  /**
+    Removes an enumerable observer. Expects the same target and method that
+    were used to register the observer.
+
+    @param {Object} target the target object to invoke
+    @param {String|Function} method the method to invoke
+
+    @returns {SC.Object} self
+  */
+  removeEnumerableObserver: function(target, method) {
+    var observers;
+
+    // Normalize parameters. If a function is passed as
+    // target, make it the method.
+    if (method === undefined) {
+      method = target;
+      target = this;
+    }
+
+    // Call the observer in the context of the enumerable
+    // if no explicit target is given.
+    if (!target) { target = this; }
+
+    // If the method is provided as a string, look it up on
+    // the target.
+    if (typeof method === "string") {
+      method = target[method];
+    }
+
+    if (!method) {
+      throw "You must pass a method to removeEnumerableObserver()";
+    }
+
+    observers = this._kvo_enumerable_observers;
+
+    if (observers) {
+      observers.remove(target, method);
+    } else {
+      throw "%@: Can't remove observers if no observer has been added.";
+    }
+
+    return this;
+  },
+
   /**
     @private
 
     Clones a segment of an observer chain and applies it
     to an element of this Enumerable.
 
+    @param {Object} item The element
     @param {SC._ChainObserver} chainObserver the chain segment to begin from
   */
   _resumeChainObservingForItemWithChainObserver: function(item, chainObserver) {
@@ -853,7 +1078,7 @@ SC.Reducers = /** @lends SC.Enumerable */ {
 
     // Maintain a list of observers on the item so we can remove them
     // if it is removed from the enumerable.
-    item._kvo_for(SC.keyFor('_kvo_enumerable_observers', key)).push(observer);
+    item._kvo_for(SC.keyFor('_kvo_content_observers', key)).push(observer);
   },
 
   /**
@@ -866,31 +1091,43 @@ SC.Reducers = /** @lends SC.Enumerable */ {
     @param {Array} addedObjects the array of objects that have been added
     @param {Array} removedObjects the array of objects that have been removed
   */
-  _setupEnumerableObservers: function(addedObjects, removedObjects) {
+  _setupContentObservers: function(addedObjects, removedObjects) {
     if (!addedObjects) { addedObjects = this; }
     if (!removedObjects) { removedObjects = []; }
 
-    var observedKeys = this._kvo_for('_kvo_enumerable_observed_keys', SC.CoreSet);
+    // Check the last values passed and skip this step if they are
+    // the same.
+    //
+    // TODO: This is obviously a suboptimal workaround to the fact that
+    // enumerableContentDidChange can get called twice when implementing
+    // SC.ArrayController. We should revisit how enumerableContentDidChange
+    // works in that context. --TD
+    var lastAdded = this._lastAdded;
+    var lastRemoved = this._lastRemoved;
+
+    if(lastAdded === addedObjects) { addedObjects = []; }
+    if(lastRemoved === removedObjects) { removedObjects = []; }
+
+    this._lastAdded = addedObjects;
+    this._lastRemoved = removedObjects;
+
+    var observedKeys = this._kvo_for('_kvo_content_observed_keys', SC.CoreSet);
     var kvoKey;
 
     // Only setup and teardown enumerable observers if we have keys to observe
     if (observedKeys.get('length') > 0) {
-      // Loop through removed objects and remove any enumerable observers that
-      // belong to them.
-      removedObjects.forEach(function(item) {
-        item._kvo_for('_kvo_enumerable_observers').forEach(function(observer) {
-          // Remove the observer if it is pointing at this enumerable.
-          // If the observer belongs to another enumerable, just ignore it.
-          if (observer.object === this) {
-            item.removeObserver(observer.key, observer, observer.propertyDidChange);
-          }
-        });
-      });
 
       // added and resume the chain observer.
       observedKeys.forEach(function(key) {
-        kvoKey = SC.keyFor('_kvo_enumerable_observers', key);
-
+        kvoKey = SC.keyFor('_kvo_content_observers', key);
+
+        // Loop through removed objects and remove any enumerable observers that
+        // belong to them.
+        removedObjects.forEach(function(item) {
+          item._kvo_for(kvoKey).forEach(function(observer) {
+            observer.destroyChain();
+          }, this);
+        }, this);
         var lastObserver;
 
         // Get all original ChainObservers associated with the key
@@ -918,28 +1155,61 @@ SC.Reducers = /** @lends SC.Enumerable */ {
   /**
     @private
 
-    Adds an enumerable observer. Enumerable observers are able to
+    Adds a content observer. Content observers are able to
     propagate chain observers to each member item in the enumerable,
     so that the observer is fired whenever a single item changes.
 
     You should never call this method directly. Instead, you should
-    call addObserver() with the special '[]' property in the path.
+    call addObserver() with the special '@each' property in the path.
 
     For example, if you wanted to observe changes to each item's isDone
     property, you could call:
 
-        arrayController.addObserver('[].isDone');
+        arrayController.addObserver('@each.isDone');
+
+    @param {SC._ChainObserver} chainObserver the chain observer to propagate
   */
-  addEnumerableObserver: function(key, target, action) {
+  _addContentObserver: function(chainObserver) {
+    var key = chainObserver.next.property;
+
     // Add the key to a set so we know what we are observing
-    this._kvo_for('_kvo_enumerable_observed_keys', SC.CoreSet).push(key);
+    this._kvo_for('_kvo_content_observed_keys', SC.CoreSet).push(key);
 
     // Add the passed ChainObserver to an ObserverSet for that key
-    var kvoKey = SC.keyFor('_kvo_enumerable_observers', key);
-    this._kvo_for(kvoKey).push(target);
+    var kvoKey = SC.keyFor('_kvo_content_observers', key);
+    this._kvo_for(kvoKey).push(chainObserver);
 
     // set up chained observers on the initial content
-    this._setupEnumerableObservers(this);
+    this._setupContentObservers(this);
+  },
+
+  /**
+    @private
+
+    Removes a content observer. Pass the same chain observer
+    that was used to add the content observer.
+
+    @param {SC._ChainObserver} chainObserver the chain observer to propagate
+  */
+
+  _removeContentObserver: function(chainObserver) {
+    var observers, kvoKey;
+    var observedKeys = this._kvo_content_observed_keys;
+    var key = chainObserver.next.property;
+
+    if (observedKeys.contains(key)) {
+
+      kvoKey = SC.keyFor('_kvo_content_observers', key);
+      observers = this._kvo_for(kvoKey);
+
+      observers.removeObject(chainObserver);
+
+      this._setupContentObservers([], this);
+
+      if (observers.length === 0) {
+        this._kvo_for('_kvo_content_observed_keys').remove(key);
+      }
+    }
   },
 
   /**
@@ -955,24 +1225,19 @@ SC.Reducers = /** @lends SC.Enumerable */ {
     property.  You can call this at the top of your unknownProperty handler
     like so:
 
-    {{{
       unknownProperty: function(key, value) {
         var ret = this.handleReduceProperty(key, value) ;
         if (ret === undefined) {
           // process like normal
         }
       }
-    }}}
 
-    @param {String} key
-      the reduce property key
+    @param {String} key the reduce property key
 
-    @param {Object} value
-      a value or undefined.
+    @param {Object} value a value or undefined.
 
-    @param {Boolean} generateProperty
-      only set to false if you do not want an optimized computed property
-      handler generated for this.  Not common.
+    @param {Boolean} generateProperty only set to false if you do not want
+      an optimized computed property handler generated for this.  Not common.
 
     @returns {Object} the reduced property or undefined
   */
@@ -1019,6 +1284,13 @@ SC.Reducers = /** @lends SC.Enumerable */ {
 
   /**
     Reducer for @max reduced property.
+
+    @param {Object} previousValue The previous value in the enumerable
+    @param {Object} item The current value in the enumerable
+    @param {Number} index The index of the current item in the enumerable
+    @param {String} reducerProperty (Optional) The property in the enumerable being reduced
+
+    @returns {Object} reduced value
   */
   reduceMax: function(previousValue, item, index, e, reducerProperty) {
     if (reducerProperty && item) {
@@ -1029,7 +1301,16 @@ SC.Reducers = /** @lends SC.Enumerable */ {
   },
 
   /**
-    Reducer for @maxObject reduced property.
+    Reduces an enumberable to the max of the items in the enumerable. If
+    reducerProperty is passed, it will reduce that property. Otherwise, it will
+    reduce the item itself.
+
+    @param {Object} previousValue The previous value in the enumerable
+    @param {Object} item The current value in the enumerable
+    @param {Number} index The index of the current item in the enumerable
+    @param {String} reducerProperty (Optional) The property in the enumerable being reduced
+
+    @returns {Object} reduced value
   */
   reduceMaxObject: function(previousItem, item, index, e, reducerProperty) {
 
@@ -1050,7 +1331,16 @@ SC.Reducers = /** @lends SC.Enumerable */ {
   },
 
   /**
-    Reducer for @min reduced property.
+    Reduces an enumberable to the min of the items in the enumerable. If
+    reducerProperty is passed, it will reduce that property. Otherwise, it will
+    reduce the item itself.
+
+    @param {Object} previousValue The previous value in the enumerable
+    @param {Object} item The current value in the enumerable
+    @param {Number} index The index of the current item in the enumerable
+    @param {String} reducerProperty (Optional) The property in the enumerable being reduced
+
+    @returns {Object} reduced value
   */
   reduceMin: function(previousValue, item, index, e, reducerProperty) {
     if (reducerProperty && item) {
@@ -1061,7 +1351,16 @@ SC.Reducers = /** @lends SC.Enumerable */ {
   },
 
   /**
-    Reducer for @maxObject reduced property.
+    Reduces an enumberable to the max of the items in the enumerable. If
+    reducerProperty is passed, it will reduce that property. Otherwise, it will
+    reduce the item itself.
+
+    @param {Object} previousValue The previous value in the enumerable
+    @param {Object} item The current value in the enumerable
+    @param {Number} index The index of the current item in the enumerable
+    @param {String} reducerProperty (Optional) The property in the enumerable being reduced
+
+    @returns {Object} reduced value
   */
   reduceMinObject: function(previousItem, item, index, e, reducerProperty) {
 
@@ -1082,7 +1381,16 @@ SC.Reducers = /** @lends SC.Enumerable */ {
   },
 
   /**
-    Reducer for @average reduced property.
+    Reduces an enumberable to the average of the items in the enumerable. If
+    reducerProperty is passed, it will reduce that property. Otherwise, it will
+    reduce the item itself.
+
+    @param {Object} previousValue The previous value in the enumerable
+    @param {Object} item The current value in the enumerable
+    @param {Number} index The index of the current item in the enumerable
+    @param {String} reducerProperty (Optional) The property in the enumerable being reduced
+
+    @returns {Object} reduced value
   */
   reduceAverage: function(previousValue, item, index, e, reducerProperty) {
     if (reducerProperty && item) {
@@ -1095,7 +1403,16 @@ SC.Reducers = /** @lends SC.Enumerable */ {
   },
 
   /**
-    Reducer for @sum reduced property.
+    Reduces an enumberable to the sum of the items in the enumerable. If
+    reducerProperty is passed, it will reduce that property. Otherwise, it will
+    reduce the item itself.
+
+    @param {Object} previousValue The previous value in the enumerable
+    @param {Object} item The current value in the enumerable
+    @param {Number} index The index of the current item in the enumerable
+    @param {String} reducerProperty (Optional) The property in the enumerable being reduced
+
+    @returns {Object} reduced value
   */
   reduceSum: function(previousValue, item, index, e, reducerProperty) {
     if (reducerProperty && item) {
@@ -1158,23 +1475,23 @@ Array.prototype.isEnumerable = YES ;
     groupBy: function(key) {
       var len = this.length,
           ret = [],
-          grouped = [], 
+          grouped = [],
           keyValues = [],
           idx, next, cur;
-      
+
       for(idx=0;idx<len;idx++) {
         next = this[idx] ;
         cur = next ? (next.get ? next.get(key) : next[key]) : null;
         if(SC.none(grouped[cur])){ grouped[cur] = []; keyValues.push(cur); }
         grouped[cur].push(next);
       }
-      
+
       for(idx=0,len=keyValues.length; idx < len; idx++){
-        ret.push(grouped[keyValues[idx]]);        
+        ret.push(grouped[keyValues[idx]]);
       }
       return ret ;
     },
-    
+
     find: function(callback, target) {
       if (typeof callback !== "function") throw new TypeError() ;
       var len = this.length ;