sproutcore 1.4.5-java → 1.5.0-java

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

@@ -1,39 +1,42 @@
 // ==========================================================================
 // 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.
-  
+
   You should implement the compare() method.
-  
+
   @since SproutCore 1.0
 */
 SC.Comparable = {
-  
+
   /**
     walk like a duck. Indicates that the object can be compared.
-    
+
     @type Boolean
   */
   isComparable: YES,
-  
+
   /**
     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
-    
-    Default implementation raises
-    an exception.
-    
+    </pre>
+
+
+    Default implementation raises an exception.
+
     @param a {Object} the first object to compare
     @param b {Object} the second object to compare
     @returns {Integer} the result of the comparison
@@ -41,5 +44,5 @@ SC.Comparable = {
   compare: function(a, b) {
     throw "%@.compare() is not implemented".fmt(this.toString());
   }
-  
+
 };

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

@@ -1,33 +1,33 @@
 // ==========================================================================
 // 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 
+  any object you create that can create a copy of itself.  This mixin is
   added automatically to the built-in array.
-  
-  You should generally implement the copy() method to return a copy of the 
+
+  You should generally implement the copy() method to return a copy of the
   receiver.
-  
+
   Note that frozenCopy() will only work if you also implement SC.Freezable.
 
   @since SproutCore 1.0
 */
-SC.Copyable = {
-  
+SC.Copyable = /** @scope SC.Copyable.prototype */{
+
   /**
     Walk like a duck.  Indicates that the object can be copied.
-    
+
     @type Boolean
   */
   isCopyable: YES,
-  
+
   /**
     Override to return a copy of the receiver.  Default implementation raises
     an exception.
@@ -38,18 +38,18 @@ SC.Copyable = {
   copy: function(deep) {
     throw "%@.copy() is not implemented";
   },
-  
+
   /**
-    If the object implements SC.Freezable, then this will return a new copy 
-    if the object is not frozen and the receiver if the object is frozen.  
-    
+    If the object implements SC.Freezable, then this will return a new copy
+    if the object is not frozen and the receiver if the object is frozen.
+
     Raises an exception if you try to call this method on a object that does
     not support freezing.
-    
+
     You should use this method whenever you want a copy of a freezable object
-    since a freezable object can simply return itself without actually 
+    since a freezable object can simply return itself without actually
     consuming more memory.
-  
+
     @returns {Object} copy of receiver or receiver
   */
   frozenCopy: function() {
@@ -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,122 +1,125 @@
 // ==========================================================================
 // 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)
 // ==========================================================================
 
-require('core') ;
-require('system/enumerator');
+sc_require('core') ;
+sc_require('ext/function');
+sc_require('system/enumerator');
 
 /*globals Prototype */
 
 /**
-  @namespace
+  @class
 
-  This mixin defines the common interface implemented by enumerable objects 
+  This mixin defines the common interface implemented by enumerable objects
   in SproutCore.  Most of these methods follow the standard Array iteration
   API defined up to JavaScript 1.8 (excluding language-specific features that
   cannot be emulated in older versions of JavaScript).
-  
+
   This mixin is applied automatically to the Array class on page load, so you
   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:
-  
+
   1. You must have a length property.  This property should change whenever
      the number of items in your enumerable object changes.  If you using this
-     with an SC.Object subclass, you should be sure to change the length 
+     with an SC.Object subclass, you should be sure to change the length
      property using set().
-     
-  2. If you must implement nextObject().  See documentation.
-    
-  Once you have these two methods implement, apply the SC.Enumerable mixin
+
+  2. You must implement nextObject().  See documentation.
+
+  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. 
-  SproutCore's API is designed to be as friendly as possible with other 
+  facility.  This is often where the most common API conflicts occur.
+  SproutCore's API is designed to be as friendly as possible with other
   libraries by implementing only methods that mostly correspond to the
-  JavaScript 1.8 API.  
-  
+  JavaScript 1.8 API.
+
   @since SproutCore 1.0
 */
-SC.Enumerable = {
+SC.Enumerable = /** @scope SC.Enumerable.prototype */{
 
-  /** 
+  /**
     Walk like a duck.
-    
-    @property {Boolean}
+
+    @type Boolean
   */
   isEnumerable: YES,
-  
+
   /**
     Implement this method to make your class enumerable.
-    
+
     This method will be call repeatedly during enumeration.  The index value
     will always begin with 0 and increment monotonically.  You don't have to
     rely on the index value to determine what object to return, but you should
     always check the value and start from the beginning when you see the
     requested index is 0.
-    
+
     The previousObject is the object that was returned from the last call
-    to nextObject for the current iteration.  This is a useful way to 
+    to nextObject for the current iteration.  This is a useful way to
     manage iteration if you are tracing a linked list, for example.
-    
-    Finally the context paramter will always contain a hash you can use as 
+
+    Finally the context paramter will always contain a hash you can use as
     a "scratchpad" to maintain any other state you need in order to iterate
-    properly.  The context object is reused and is not reset between 
+    properly.  The context object is reused and is not reset between
     iterations so make sure you setup the context with a fresh state whenever
     the index parameter is 0.
-    
+
     Generally iterators will continue to call nextObject until the index
-    reaches the your current length-1.  If you run out of data before this 
+    reaches the your current length-1.  If you run out of data before this
     time for some reason, you should simply return undefined.
-    
+
     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.
-    @returns {Object} the next object in the iteration or undefined   
-  */ 
+
+    @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) {
     return this.objectAt ? this.objectAt(index) : this[index] ;
   },
-  
+
   /**
     Helper method returns the first object from a collection.  This is usually
-    used by bindings and other parts of the framework to extract a single 
+    used by bindings and other parts of the framework to extract a single
     object if the enumerable contains only one item.
-    
-    If you override this method, you should implement it so that it will 
+
+    If you override this method, you should implement it so that it will
     always return the same value each time it is called.  If your enumerable
     contains only one object, this method should always return that object.
     If your enumerable is empty, this method should return undefined.
-    
+
     @returns {Object} the object or undefined
   */
   firstObject: function() {
     if (this.get('length')===0) return undefined ;
     if (this.objectAt) return this.objectAt(0); // support arrays out of box
-    
+
     // handle generic enumerables
     var context = SC.Enumerator._popContext(), ret;
     ret = this.nextObject(0, null, context);
-    context = SC.Enumerator._pushContext(context);  
+    context = SC.Enumerator._pushContext(context);
     return ret ;
   }.property(),
-  
+
   /**
     Helper method returns the last object from a collection.
-    
+
     @returns {Object} the object or undefined
   */
   lastObject: function() {
@@ -124,45 +127,43 @@ SC.Enumerable = {
     if (len===0) return undefined ;
     if (this.objectAt) return this.objectAt(len-1); // support arrays out of box
   }.property(),
-  
+
   /**
     Returns a new enumerator for this object.  See SC.Enumerator for
     documentation on how to use this object.  Enumeration is an alternative
     to using one of the other iterators described here.
-    
+
     @returns {SC.Enumerator} an enumerator for the receiver
   */
   enumerator: function() { return SC.Enumerator.create(this); },
-  
+
   /**
     Iterates through the enumerable, calling the passed function on each
-    item.  This method corresponds to the forEach() method defined in 
+    item.  This method corresponds to the forEach() method defined in
     JavaScript 1.6.
-    
+
     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
     - *enumerable* is the enumerable object itself.
-    
+
     Note that in addition to a callback, you can also pass an optional target
     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) {
     if (typeof callback !== "function") throw new TypeError() ;
     var len = this.get ? this.get('length') : this.length ;
     if (target === undefined) target = null;
-    
+
     var last = null ;
     var context = SC.Enumerator._popContext();
     for(var idx=0;idx<len;idx++) {
@@ -174,13 +175,13 @@ SC.Enumerable = {
     context = SC.Enumerator._pushContext(context);
     return this ;
   },
-  
+
   /**
     Retrieves the named value on each member object.  This is more efficient
-    than using one of the wrapper methods defined here.  Objects that 
+    than using one of the wrapper methods defined here.  Objects that
     implement SC.Observable will use the get() method, otherwise the property
     will be accessed directly.
-    
+
     @param {String} key the key to retrieve
     @returns {Array} extracted values
   */
@@ -195,7 +196,7 @@ SC.Enumerable = {
     efficient than using other methods defined on this helper.  If the object
     implements SC.Observable, the value will be changed to set(), otherwise
     it will be set directly.  null objects are skipped.
-    
+
     @param {String} key the key to set
     @param {Object} value the object to set
     @returns {Object} receiver
@@ -209,37 +210,35 @@ SC.Enumerable = {
     }, this);
     return this ;
   },
-  
+
   /**
-    Maps all of the items in the enumeration to another value, returning 
+    Maps all of the items in the enumeration to another value, returning
     a new array.  This method corresponds to map() defined in JavaScript 1.6.
-    
+
     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
     - *enumerable* is the enumerable object itself.
-    
+
     It should return the mapped value.
-    
+
     Note that in addition to a callback, you can also pass an optional target
     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) {
     if (typeof callback !== "function") throw new TypeError() ;
     var len = this.get ? this.get('length') : this.length ;
     if (target === undefined) target = null;
-    
+
     var ret  = [];
     var last = null ;
     var context = SC.Enumerator._popContext();
@@ -256,47 +255,45 @@ 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) {
-    return this.map(function(next) { 
+    return this.map(function(next) {
       return next ? (next.get ? next.get(key) : next[key]) : null;
     });
   },
 
   /**
     Returns an array with all of the items in the enumeration that the passed
-    function returns YES for. This method corresponds to filter() defined in 
+    function returns YES for. This method corresponds to filter() defined in
     JavaScript 1.6.
-    
+
     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
     - *enumerable* is the enumerable object itself.
-    
+
     It should return the YES to include the item in the results, NO otherwise.
-    
+
     Note that in addition to a callback, you can also pass an optional target
     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) {
     if (typeof callback !== "function") throw new TypeError() ;
     var len = this.get ? this.get('length') : this.length ;
     if (target === undefined) target = null;
-    
+
     var ret  = [];
     var last = null ;
     var context = SC.Enumerator._popContext();
@@ -310,11 +307,11 @@ SC.Enumerable = {
     return ret ;
   },
 
-  /** 
+  /**
     Returns an array sorted by the value of the passed key parameters.
     null objects will be sorted first.  You can pass either an array of keys
     or multiple parameters which will act as key names
-    
+
     @param {String} key one or more key names
     @returns {Array}
   */
@@ -322,18 +319,18 @@ SC.Enumerable = {
     var keys = (typeof key === SC.T_STRING) ? arguments : key,
         len  = keys.length,
         src;
-     
-    // get the src array to sort   
+
+    // get the src array to sort
     if (this instanceof Array) src = this;
     else {
       src = [];
       this.forEach(function(i) { src.push(i); });
     }
-    
+
     if (!src) return [];
     return src.sort(function(a,b) {
       var idx, key, aValue, bValue, ret = 0;
-      
+
       for(idx=0;ret===0 && idx<len;idx++) {
         key = keys[idx];
         aValue = a ? (a.get ? a.get(key) : a[key]) : null;
@@ -343,15 +340,15 @@ SC.Enumerable = {
       return ret ;
     });
   },
-  
+
 
   /**
     Returns an array with just the items with the matched property.  You
     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) {
@@ -370,7 +367,7 @@ SC.Enumerable = {
     context = SC.Enumerator._pushContext(context);
     return ret ;
   },
-    
+
   /**
     Returns the first item in the array for which the callback returns YES.
     This method works similar to the filter() method defined in JavaScript 1.6
@@ -379,9 +376,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 +388,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) {
@@ -417,11 +412,11 @@ SC.Enumerable = {
     Returns an the first item with a property matching the passed value.  You
     can pass an optional second argument with the target value.  Otherwise
     this will match any property that evaluates to true.
-    
+
     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) {
@@ -439,43 +434,39 @@ SC.Enumerable = {
     context = SC.Enumerator._pushContext(context);
     return ret ;
   },
-      
+
   /**
     Returns YES if the passed function returns YES for every item in the
     enumeration.  This corresponds with the every() method in JavaScript 1.6.
-    
+
     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
     - *enumerable* is the enumerable object itself.
-    
+
     It should return the YES or NO.
-    
+
     Note that in addition to a callback, you can also pass an optional target
     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
-    
-    {{{
-      if (people.every(isEngineer)) { Paychecks.addBigBonus(); }
-    }}}
-    
-    @params callback {Function} the callback to execute
-    @params target {Object} the target object to use
-    @returns {Boolean} 
+
+    Example Usage:
+
+          if (people.every(isEngineer)) { Paychecks.addBigBonus(); }
+
+    @param {Function} callback the callback to execute
+    @param {Object} target the target object to use
+    @returns {Boolean}
   */
   every: function(callback, target) {
     if (typeof callback !== "function") throw new TypeError() ;
     var len = this.get ? this.get('length') : this.length ;
     if (target === undefined) target = null;
-    
+
     var ret  = YES;
     var last = null ;
     var context = SC.Enumerator._popContext();
@@ -493,8 +484,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) {
@@ -512,44 +503,40 @@ SC.Enumerable = {
     context = SC.Enumerator._pushContext(context);
     return ret ;
   },
-  
-  
+
+
   /**
-    Returns YES if the passed function returns true for any item in the 
+    Returns YES if the passed function returns true for any item in the
     enumeration. This corresponds with the every() method in JavaScript 1.6.
-    
+
     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
     - *enumerable* is the enumerable object itself.
-    
+
     It should return the YES to include the item in the results, NO otherwise.
-    
+
     Note that in addition to a callback, you can also pass an optional target
     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
-    
-    {{{
-      if (people.some(isManager)) { Paychecks.addBiggerBonus(); }
-    }}}
-    
-    @params callback {Function} the callback to execute
-    @params target {Object} the target object to use
+
+    Usage Example:
+
+          if (people.some(isManager)) { Paychecks.addBiggerBonus(); }
+
+    @param {Function} callback the callback to execute
+    @param {Object} target the target object to use
     @returns {Array} A filtered array.
   */
   some: function(callback, target) {
     if (typeof callback !== "function") throw new TypeError() ;
     var len = this.get ? this.get('length') : this.length ;
     if (target === undefined) target = null;
-    
+
     var ret  = NO;
     var last = null ;
     var context = SC.Enumerator._popContext();
@@ -567,9 +554,9 @@ 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.
-    @returns {Boolean} YES 
+    @param {String} key the property to test
+    @param {String} value optional value to test against.
+    @returns {Boolean} YES
   */
   someProperty: function(key, value) {
     var len = this.get ? this.get('length') : this.length ;
@@ -588,17 +575,15 @@ SC.Enumerable = {
   },
 
   /**
-    This will combine the values of the enumerator into a single value. It 
+    This will combine the values of the enumerator into a single value. It
     is a useful way to collect a summary value from an enumeration.  This
     corresponds to the reduce() method defined in JavaScript 1.8.
-    
+
     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.
     - *index* is the current index in the iteration
@@ -610,14 +595,14 @@ SC.Enumerable = {
     will be raised if you do not pass an initial value and the enumerator is
     empty.
 
-    Note that unlike the other methods, this method does not allow you to 
+    Note that unlike the other methods, this method does not allow you to
     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() ;
@@ -625,13 +610,13 @@ SC.Enumerable = {
 
     // no value to return if no initial value & empty
     if (len===0 && initialValue === undefined) throw new TypeError();
-    
+
     var ret  = initialValue;
     var last = null ;
     var context = SC.Enumerator._popContext();
     for(var idx=0;idx<len;idx++) {
       var next = this.nextObject(idx, last, context) ;
-      
+
       // while ret is still undefined, just set the first value we get as ret.
       // this is not the ideal behavior actually but it matches the FireFox
       // implementation... :(
@@ -646,34 +631,34 @@ SC.Enumerable = {
     }
     last = null ;
     context = SC.Enumerator._pushContext(context);
-    
+
     // uh oh...we never found a value!
     if (ret === undefined) throw new TypeError() ;
     return ret ;
   },
-  
+
   /**
     Invokes the named method on every object in the receiver that
     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) {
     var len = this.get ? this.get('length') : this.length ;
     if (len <= 0) return [] ; // nothing to invoke....
-    
+
     var idx;
-    
+
     // collect the arguments
     var args = [] ;
     var alen = arguments.length ;
     if (alen > 1) {
       for(idx=1;idx<alen;idx++) args.push(arguments[idx]) ;
     }
-    
+
     // call invoke
     var ret = [] ;
     var last = null ;
@@ -691,13 +676,13 @@ SC.Enumerable = {
 
   /**
     Invokes the passed method and optional arguments on the receiver elements
-    as long as the methods return value matches the target value.  This is 
+    as long as the methods return value matches the target value.  This is
     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) {
@@ -712,7 +697,7 @@ SC.Enumerable = {
     if (alen > 2) {
       for(idx=2;idx<alen;idx++) args.push(arguments[idx]) ;
     }
-    
+
     // call invoke
     var ret = targetValue ;
     var last = null ;
@@ -727,12 +712,12 @@ SC.Enumerable = {
     context = SC.Enumerator._pushContext(context);
     return ret ;
   },
-  
+
   /**
     Simply converts the enumerable into a genuine array.  The order, of
-    course, is not gauranteed.  Corresponds to the method implemented by 
+    course, is not gauranteed.  Corresponds to the method implemented by
     Prototype.
-        
+
     @returns {Array} the enumerable as an array.
   */
   toArray: function() {
@@ -740,37 +725,41 @@ SC.Enumerable = {
     this.forEach(function(o) { ret.push(o); }, this);
     return ret ;
   },
-  
+
   /**
-    Converts an enumerable into a matrix, with inner arrays grouped based 
+    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){
     var len = this.get ? this.get('length') : this.length,
         ret = [],
         last = null,
         context = SC.Enumerator._popContext(),
-        grouped = [], 
-        keyValues = [];          
-    for(var idx=0;idx<len;idx++) {
-      var next = this.nextObject(idx, last, context) ;
-      var cur = next ? (next.get ? next.get(key) : next[key]) : null;
-      if(SC.none(grouped[cur])){ grouped[cur] = []; keyValues.push(cur); }
+        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])) {
+        grouped[cur] = []; keyValues.push(cur);
+      }
       grouped[cur].push(next);
       last = next;
     }
     last = null;
     context = SC.Enumerator._pushContext(context);
-    
-    for(var idx=0,len2=keyValues.length; idx < len2; idx++){
-      ret.push(grouped[keyValues[idx]]);        
+
+    for(idx=0,len=keyValues.length; idx < len; idx++){
+      ret.push(grouped[keyValues[idx]]);
     }
     return ret ;
   }
-  
+
 } ;
 
 // Build in a separate function to avoid unintential leaks through closures...
@@ -781,7 +770,7 @@ SC._buildReducerFor = function(reducerKey, reducerProperty) {
       return this.unknownProperty ? this.unknownProperty(key, value) : null;
     } else {
       // Invoke the reduce method defined in enumerable instead of using the
-      // one implemented in the receiver.  The receiver might be a native 
+      // one implemented in the receiver.  The receiver might be a native
       // implementation that does not support reducerProperty.
       var ret = SC.Enumerable.reduce.call(this, reducer, null, reducerProperty) ;
       return ret ;
@@ -789,15 +778,16 @@ 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
     content.
-    
+
     For plain enumerables, this property is read only.  SC.Array overrides
     this method.
-    
+
     @property {SC.Array}
   */
   '[]': function(key, value) { return this ; }.property(),
@@ -805,70 +795,67 @@ SC.Reducers = /** @lends SC.Enumerable */ {
   /**
     Invoke this method when the contents of your enumerable has changed.
     This will notify any observers watching for content changes.  If your are
-    implementing an ordered enumerable (such as an array), also pass the 
+    implementing an ordered enumerable (such as an array), also pass the
     start and end values where the content changed so that it can be used to
     notify range observers.
-    
+
     @param {Number} start optional start offset for the content change
     @param {Number} length optional length of change
-    @returns {Object} receiver 
+    @param {Number} delta if you added or removed objects, the delta change
+    @param {Array} addedObjects the objects that were added
+    @param {Array} removedObjects the objects that were removed
+    @returns {Object} receiver
   */
-  enumerableContentDidChange: function(start, length) {
+  enumerableContentDidChange: function(start, length, deltas) {
     this.notifyPropertyChange('[]') ;
-    return this ;
   },
-  
+
   /**
-    Call this method from your unknownProperty() handler to implement 
-    automatic reduced properties.  A reduced property is a property that 
-    collects its contents dynamically from your array contents.  Reduced 
-    properties always begin with "@".  Getting this property will call 
+    Call this method from your unknownProperty() handler to implement
+    automatic reduced properties.  A reduced property is a property that
+    collects its contents dynamically from your array contents.  Reduced
+    properties always begin with "@".  Getting this property will call
     reduce() on your array with the function matching the key name as the
     processor.
-    
-    The return value of this will be either the return value from the 
-    reduced property or undefined, which means this key is not a reduced 
+
+    The return value of this will be either the return value from the
+    reduced property or undefined, which means this key is not a reduced
     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 {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 {String} key the reduce property key
+
+    @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.
+
     @returns {Object} the reduced property or undefined
   */
   reducedProperty: function(key, value, generateProperty) {
-     
-    if (!key || key.charAt(0) !== '@') return undefined ; // not a reduced property
-    
+
+    if (!key || typeof key !== SC.T_STRING || key.charAt(0) !== '@') return undefined ; // not a reduced property
+
     // get the reducer key and the reducer
     var matches = key.match(/^@([^(]*)(\(([^)]*)\))?$/) ;
     if (!matches || matches.length < 2) return undefined ; // no match
-    
+
     var reducerKey = matches[1]; // = 'max' if key = '@max(balance)'
     var reducerProperty = matches[3] ; // = 'balance' if key = '@max(balance)'
     reducerKey = "reduce" + reducerKey.slice(0,1).toUpperCase() + reducerKey.slice(1);
     var reducer = this[reducerKey] ;
 
-    // if there is no reduce function defined for this key, then we can't 
+    // if there is no reduce function defined for this key, then we can't
     // build a reducer for it.
     if (SC.typeOf(reducer) !== SC.T_FUNCTION) return undefined;
-    
+
     // if we can't generate the property, just run reduce
     if (generateProperty === NO) {
       return SC.Enumerable.reduce.call(this, reducer, null, reducerProperty) ;
@@ -877,10 +864,10 @@ SC.Reducers = /** @lends SC.Enumerable */ {
     // ok, found the reducer.  Let's build the computed property and install
     var func = SC._buildReducerFor(reducerKey, reducerProperty);
     var p = this.constructor.prototype ;
-    
+
     if (p) {
       p[key] = func ;
-      
+
       // add the function to the properties array so that new instances
       // will have their dependent key registered.
       var props = p._properties || [] ;
@@ -888,13 +875,20 @@ SC.Reducers = /** @lends SC.Enumerable */ {
       p._properties = props ;
       this.registerDependentKey(key, '[]') ;
     }
-    
+
     // and reduce anyway...
     return SC.Enumerable.reduce.call(this, reducer, null, reducerProperty) ;
   },
-  
-  /** 
+
+  /**
     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) {
@@ -904,11 +898,20 @@ SC.Reducers = /** @lends SC.Enumerable */ {
     return (item > previousValue) ? item : previousValue ;
   },
 
-  /** 
-    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) {
-    
+
     // get the value for both the previous and current item.  If no
     // reducerProperty was supplied, use the items themselves.
     var previousValue = previousItem, itemValue = item ;
@@ -916,7 +919,7 @@ SC.Reducers = /** @lends SC.Enumerable */ {
       if (item) {
         itemValue = item.get ? item.get(reducerProperty) : item[reducerProperty] ;
       }
-      
+
       if (previousItem) {
         previousValue = previousItem.get ? previousItem.get(reducerProperty) : previousItem[reducerProperty] ;
       }
@@ -925,8 +928,17 @@ SC.Reducers = /** @lends SC.Enumerable */ {
     return (itemValue > previousValue) ? item : previousItem ;
   },
 
-  /** 
-    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) {
@@ -936,8 +948,17 @@ SC.Reducers = /** @lends SC.Enumerable */ {
     return (item < previousValue) ? item : previousValue ;
   },
 
-  /** 
-    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) {
 
@@ -948,7 +969,7 @@ SC.Reducers = /** @lends SC.Enumerable */ {
       if (item) {
         itemValue = item.get ? item.get(reducerProperty) : item[reducerProperty] ;
       }
-      
+
       if (previousItem) {
         previousValue = previousItem.get ? previousItem.get(reducerProperty) : previousItem[reducerProperty] ;
       }
@@ -957,8 +978,17 @@ SC.Reducers = /** @lends SC.Enumerable */ {
     return (itemValue < previousValue) ? item : previousItem ;
   },
 
-  /** 
-    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) {
@@ -967,11 +997,20 @@ SC.Reducers = /** @lends SC.Enumerable */ {
     var ret = (previousValue || 0) + item ;
     var len = e.get ? e.get('length') : e.length;
     if (index >= len-1) ret = ret / len; //avg after last item.
-    return ret ; 
+    return ret ;
   },
 
-  /** 
-    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) {
@@ -993,11 +1032,11 @@ Array.prototype.isEnumerable = YES ;
 // Implement the same enhancements on Array.  We use specialized methods
 // because working with arrays are so common.
 (function() {
-  
+
   // These methods will be applied even if they already exist b/c we do it
   // better.
   var alwaysMixin = {
-    
+
     // this is supported so you can get an enumerator.  The rest of the
     // methods do not use this just to squeeze every last ounce of perf as
     // possible.
@@ -1006,7 +1045,7 @@ Array.prototype.isEnumerable = YES ;
     firstObject: SC.Enumerable.firstObject,
     lastObject: SC.Enumerable.lastObject,
     sortProperty: SC.Enumerable.sortProperty,
-    
+
     // see above...
     mapProperty: function(key) {
       var len = this.length ;
@@ -1028,27 +1067,29 @@ Array.prototype.isEnumerable = YES ;
         if (matched) ret.push(next) ;
       }
       return ret ;
-    },    
+    },
 
     //returns a matrix
     groupBy: function(key) {
       var len = this.length,
           ret = [],
-          grouped = [], 
-          keyValues = [];          
-      for(var idx=0;idx<len;idx++) {
-        var next = this[idx] ;
-        var cur = next ? (next.get ? next.get(key) : next[key]) : null;
+          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(var idx=0,len2=keyValues.length; idx < len2; idx++){
-        ret.push(grouped[keyValues[idx]]);        
+
+      for(idx=0,len=keyValues.length; idx < len; idx++){
+        ret.push(grouped[keyValues[idx]]);
       }
       return ret ;
-    },    
+    },
 
-    
     find: function(callback, target) {
       if (typeof callback !== "function") throw new TypeError() ;
       var len = this.length ;
@@ -1073,7 +1114,7 @@ Array.prototype.isEnumerable = YES ;
       }
       next=null;
       return ret ;
-    },    
+    },
 
     everyProperty: function(key, value) {
       var len = this.length ;
@@ -1085,7 +1126,7 @@ Array.prototype.isEnumerable = YES ;
       }
       return ret ;
     },
-    
+
     someProperty: function(key, value) {
       var len = this.length ;
       var ret  = NO;
@@ -1096,7 +1137,7 @@ Array.prototype.isEnumerable = YES ;
       }
       return ret ;  // return the invert
     },
-    
+
     invoke: function(methodName) {
       var len = this.length ;
       if (len <= 0) return [] ; // nothing to invoke....
@@ -1155,7 +1196,7 @@ Array.prototype.isEnumerable = YES ;
       }
       return ret ;
     },
-    
+
     getEach: function(key) {
       var ret = [];
       var len = this.length ;
@@ -1165,7 +1206,7 @@ Array.prototype.isEnumerable = YES ;
       }
       return ret ;
     },
-    
+
     setEach: function(key, value) {
       var len = this.length;
       for(var idx=0;idx<len;idx++) {
@@ -1178,47 +1219,49 @@ Array.prototype.isEnumerable = YES ;
       }
       return this ;
     }
-    
-  }; 
-  
-  // These methods will only be applied if they are not already defined b/c 
+
+  };
+
+  // These methods will only be applied if they are not already defined b/c
   // the browser is probably getting it.
   var mixinIfMissing = {
 
+    // QUESTION: The lack of DRY is burning my eyes [YK]
     forEach: function(callback, target) {
       if (typeof callback !== "function") throw new TypeError() ;
-      var len = this.length ;
+
+      // QUESTION: Is this necessary?
       if (target === undefined) target = null;
 
-      for(var idx=0;idx<len;idx++) {
-        var next = this[idx] ;
-        callback.call(target, next, idx, this);
+      for(var i=0, l=this.length; i<l; i++) {
+        var next = this[i] ;
+        callback.call(target, next, i, this);
       }
       return this ;
     },
 
     map: function(callback, target) {
       if (typeof callback !== "function") throw new TypeError() ;
-      var len = this.length ;
+
       if (target === undefined) target = null;
 
       var ret  = [];
-      for(var idx=0;idx<len;idx++) {
-        var next = this[idx] ;
-        ret[idx] = callback.call(target, next, idx, this) ;
+      for(var i=0, l=this.length; i<l; i++) {
+        var next = this[i] ;
+        ret[i] = callback.call(target, next, i, this) ;
       }
       return ret ;
     },
 
     filter: function(callback, target) {
       if (typeof callback !== "function") throw new TypeError() ;
-      var len = this.length ;
+
       if (target === undefined) target = null;
 
       var ret  = [];
-      for(var idx=0;idx<len;idx++) {
-        var next = this[idx] ;
-        if(callback.call(target, next, idx, this)) ret.push(next) ;
+      for(var i=0, l=this.length; i<l; i++) {
+        var next = this[i] ;
+        if(callback.call(target, next, i, this)) ret.push(next) ;
       }
       return ret ;
     },
@@ -1260,8 +1303,8 @@ Array.prototype.isEnumerable = YES ;
       for(var idx=0;idx<len;idx++) {
         var next = this[idx] ;
 
-        // while ret is still undefined, just set the first value we get as 
-        // ret. this is not the ideal behavior actually but it matches the 
+        // while ret is still undefined, just set the first value we get as
+        // ret. this is not the ideal behavior actually but it matches the
         // FireFox implementation... :(
         if (next !== null) {
           if (ret === undefined) {
@@ -1275,24 +1318,24 @@ Array.prototype.isEnumerable = YES ;
       // uh oh...we never found a value!
       if (ret === undefined) throw new TypeError() ;
       return ret ;
-    }   
+    }
   };
-  
+
   // Apply methods if missing...
   for(var key in mixinIfMissing) {
     if (!mixinIfMissing.hasOwnProperty(key)) continue ;
-    
+
     // The mixinIfMissing methods should be applied if they are not defined.
     // If Prototype 1.6 is included, some of these methods will be defined
-    // already, but we want to override them anyway in this special case 
+    // already, but we want to override them anyway in this special case
     // because our version is faster and functionally identitical.
     if (!Array.prototype[key] || ((typeof Prototype === 'object') && Prototype.Version.match(/^1\.6/))) {
       Array.prototype[key] = mixinIfMissing[key] ;
     }
   }
-  
+
   // Apply other methods...
   SC.mixin(Array.prototype, alwaysMixin) ;
-  
+
 })() ;