sproutcore 1.4.5-java → 1.5.0-java

data/lib/frameworks/sproutcore/frameworks/runtime/system/enumerator.js

@@ -1,22 +1,22 @@
 // ==========================================================================
 // 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)
 // ==========================================================================
 
 /**
   @class
-  
-  An object that iterates over all of the values in an object.  
-  
-  An instance of this object is returned everytime you call the 
+
+  An object that iterates over all of the values in an object.
+
+  An instance of this object is returned everytime you call the
   enumerator() method on an object that implements the SC.Enumerable mixin.
-  
+
   Once you create an enumerator instance, you can call nextObject() on it
   until you can iterated through the entire collection.  Once you have
   exhausted the enumerator, you can reuse it if you want by calling reset().
-  
+
   @since SproutCore 1.0
 */
 SC.Enumerator = function(enumerableObject) {
@@ -25,34 +25,34 @@ SC.Enumerator = function(enumerableObject) {
   return this ;
 } ;
 
-SC.Enumerator.prototype = {
-  
-  /** 
+SC.Enumerator.prototype = /** @scope SC.Enumerator.prototype */{
+
+  /**
     Returns the next object in the enumeration or undefined when complete.
-    
+
     @returns {Object} the next object or undefined
   */
   nextObject: function() {
     var index = this._index ;
     var len = this._length;
     if (index >= len) return undefined ; // nothing to do
-    
+
     // get the value
     var ret = this.enumerable.nextObject(index, this._previousObject, this._context) ;
     this._previousObject = ret ;
     this._index = index + 1 ;
-    
+
     if (index >= len) {
-      this._context = SC.Enumerator._pushContext(this._context); 
+      this._context = SC.Enumerator._pushContext(this._context);
     }
-    
+
     return ret ;
   },
-  
+
   /**
     Resets the enumerator to the beginning.  This is a nice way to reuse
-    an existing enumerator. 
-    
+    an existing enumerator.
+
     @returns {Object} this
   */
   reset: function() {
@@ -64,18 +64,18 @@ SC.Enumerator.prototype = {
     this._previousObject = null ;
     this._context = (len > 0) ? SC.Enumerator._popContext() : null;
   },
-  
+
   /**
     Releases the enumerators enumerable object.  You cannot use this object
-    anymore.  This is not often needed but it is useful when you need to 
+    anymore.  This is not often needed but it is useful when you need to
     make sure memory gets cleared.
-    
-    @returns {Object} null 
+
+    @returns {Object} null
   */
   destroy: function() {
     this.enumerable = this._length = this._index = this._previousObject = this._context = null;
   }
-  
+
 } ;
 
 /**
@@ -103,5 +103,5 @@ SC.Enumerator._pushContext = function(context) {
   var cache = this._contextCache;
   cache.push(context);
   return null ;
-}; 
+};
 

data/lib/frameworks/sproutcore/frameworks/runtime/system/error.js

@@ -1,78 +1,82 @@
 // ==========================================================================
 // Project:   SproutCore - JavaScript Application Framework
 // 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)
 // ==========================================================================
+// @global SC
+
+sc_require('ext/function');
 
 /**
   @class
-  
+
   An error, used to represent an error state.
-  
+
   Many API's within SproutCore will return an instance of this object whenever
   they have an error occur.  An error includes an error code, description,
-  and optional human readable label that indicates the item that failed. 
-  
+  and optional human readable label that indicates the item that failed.
+
   Depending on the error, other properties may also be added to the object
   to help you recover from the failure.
-  
+
   You can pass error objects to various UI elements to display the error in
-  the interface. You can easily determine if the value returned by some API is 
+  the interface. You can easily determine if the value returned by some API is
   an error or not using the helper SC.ok(value).
-  
-  h2. Faking Error Objects
-  
+
+  Faking Error Objects
+  ---
+
   You can actually make any object you want to be treated like an Error object
-  by simply implementing two properties: isError and errorValue.  If you 
+  by simply implementing two properties: isError and errorValue.  If you
   set isError to YES, then calling SC.ok(obj) on your object will return NO.
-  If isError is YES, then SC.val(obj) will return your errorValue property 
+  If isError is YES, then SC.val(obj) will return your errorValue property
   instead of the receiver.
-  
+
   @extends SC.Object
   @since SproutCore 1.0
 */
 SC.Error = SC.Object.extend(
 /** @scope SC.Error.prototype */ {
-  
+
   /**
     error code.  Used to designate the error type.
-    
-    @property {Number}
+
+    @type Number
   */
   code: -1,
-  
+
   /**
     Human readable description of the error.  This can also be a non-localized
     key.
-    
-    @property {String}
+
+    @type String
   */
   message: '',
-  
+
   /**
     The value the error represents.  This is used when wrapping a value inside
     of an error to represent the validation failure.
-    
-    @property {Object}
+
+    @type Object
   */
   errorValue: null,
-  
+
   /**
-    The original error object.  Normally this will return the receiver.  
+    The original error object.  Normally this will return the receiver.
     However, sometimes another object will masquarade as an error; this gives
     you a way to get at the underyling error.
-    
-    @property {SC.Error}
+
+    @type SC.Error
   */
   errorObject: function() {
     return this;
   }.property().cacheable(),
-  
+
   /**
     Human readable name of the item with the error.
-    
-    @property {String}
+
+    @type String
   */
   label: null,
 
@@ -80,11 +84,11 @@ SC.Error = SC.Object.extend(
   toString: function() {
     return "SC.Error:%@:%@ (%@)".fmt(SC.guidFor(this), this.get('message'), this.get('code'));
   },
-  
+
   /**
     Walk like a duck.
-    
-    @property {Boolean}
+
+    @type Boolean
   */
   isError: YES
 }) ;
@@ -92,7 +96,7 @@ SC.Error = SC.Object.extend(
 /**
   Creates a new SC.Error instance with the passed description, label, and
   code.  All parameters are optional.
-  
+
   @param description {String} human readable description of the error
   @param label {String} human readable name of the item with the error
   @param code {Number} an error code to use for testing.
@@ -114,13 +118,14 @@ SC.Error.desc = function(description, label, value, code) {
   @param code {Number} an error code to use for testing.
   @returns {SC.Error} new error instance.
 */
-SC.$error = function(description, label, value, c) { 
-  return SC.Error.desc(description,label, value, c); 
+
+SC.$error = function(description, label, value, c) {  
+  return SC.Error.desc(description,label, value, c);
 } ;
 
 /**
   Returns YES if the passed value is an error object or false.
-  
+
   @param {Object} ret object value
   @returns {Boolean}
 */
@@ -134,9 +139,9 @@ SC.$ok = SC.ok;
 /**
   Returns the value of an object.  If the passed object is an error, returns
   the value associated with the error; otherwise returns the receiver itself.
-  
+
   @param {Object} obj the object
-  @returns {Object} value 
+  @returns {Object} value
 */
 SC.val = function(obj) {
   if (obj && obj.isError) {
@@ -151,7 +156,7 @@ SC.$val = SC.val;
 
 /**
   Standard error code for errors that do not support multiple values.
-  
-  @property {Number}
+
+  @type Number
 */
 SC.Error.HAS_MULTIPLE_VALUES = -100 ;

data/lib/frameworks/sproutcore/frameworks/runtime/system/function.js

@@ -0,0 +1,76 @@
+// ==========================================================================
+// Project:   SproutCore Costello - Property Observing Library
+// Copyright: ©2006-2011 Strobe Inc. and contributors.
+//            Portions ©2008-2011 Apple Inc. All rights reserved.
+// License:   Licensed under MIT license (see license.js)
+// ==========================================================================
+
+/**
+  @class
+*/
+SC.Function = /** @scope SC.Function.prototype */{
+
+  /**
+    @see Function.prototype.property
+  */
+  property: function(fn, keys) {
+    fn.dependentKeys = SC.$A(keys) ;
+    var guid = SC.guidFor(fn) ;
+    fn.cacheKey = "__cache__" + guid ;
+    fn.lastSetValueKey = "__lastValue__" + guid ;
+    fn.isProperty = true ;
+    return fn ;
+  },
+
+  /**
+    @see Function.prototype.cacheable
+  */
+  cacheable: function(fn, aFlag) {
+    fn.isProperty = true ;  // also make a property just in case
+    if (!fn.dependentKeys) fn.dependentKeys = [] ;
+    fn.isCacheable = (aFlag === undefined) ? true : aFlag ;
+    return fn ;
+  },
+
+  /**
+    @see Function.prototype.idempotent
+  */
+  idempotent: function(fn, aFlag) {
+    fn.isProperty = true;  // also make a property just in case
+    if (!fn.dependentKeys) this.dependentKeys = [] ;
+    fn.isVolatile = (aFlag === undefined) ? true : aFlag ;
+    return fn ;
+  },
+
+  /**
+    @see Function.prototype.enhance
+  */
+  enhance: function(fn) {
+    fn.isEnhancement = true;
+    return fn ;
+  },
+
+  /**
+    @see Function.prototype.observes
+  */
+  observes: function(fn, propertyPaths) {
+    // sort property paths into local paths (i.e just a property name) and
+    // full paths (i.e. those with a . or * in them)
+    var loc = propertyPaths.length, local = null, paths = null ;
+    while(--loc >= 0) {
+      var path = propertyPaths[loc] ;
+      // local
+      if ((path.indexOf('.')<0) && (path.indexOf('*')<0)) {
+        if (!local) local = fn.localPropertyPaths = [] ;
+        local.push(path);
+
+      // regular
+      } else {
+        if (!paths) paths = fn.propertyPaths = [] ;
+        paths.push(path) ;
+      }
+    }
+    return fn ;
+  }
+
+};

data/lib/frameworks/sproutcore/frameworks/runtime/system/index_set.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,44 +11,44 @@ sc_require('mixins/freezable');
 sc_require('mixins/copyable');
 
 /**
-  @class 
+  @class
 
   A collection of ranges.  You can use an IndexSet to keep track of non-
-  continuous ranges of items in a parent array.  IndexSet's are used for 
+  continuous ranges of items in a parent array.  IndexSet's are used for
   selection, for managing invalidation ranges and other data-propogation.
 
-  h2. Examples
-  
-  {{{
-    var set = SC.IndexSet.create(ranges) ;
-    set.contains(index);
-    set.add(index, length);
-    set.remove(index, length);
-    
-    // uses a backing SC.Array object to return each index
-    set.forEach(function(object) { .. })
-    
-    // returns the index
-    set.forEachIndex(function(index) { ... });
-    
-    // returns ranges
-    set.forEachRange(function(start, length) { .. });
-  }}}
-
-  h2. Implementation Notes
+  Examples
+  ---
+
+        var set = SC.IndexSet.create(ranges) ;
+        set.contains(index);
+        set.add(index, length);
+        set.remove(index, length);
+
+        // uses a backing SC.Array object to return each index
+        set.forEach(function(object) { .. })
+
+        // returns the index
+        set.forEachIndex(function(index) { ... });
+
+        // returns ranges
+        set.forEachRange(function(start, length) { .. });
+
+  Implementation Notes
+  ---
 
   An IndexSet stores indices on the object.  A positive value great than the
   index tells you the end of an occupied range.  A negative values tells you
-  the end of an empty range.  A value less than the index is a search 
+  the end of an empty range.  A value less than the index is a search
   accelerator.  It tells you the start of the nearest range.
 
-  @extends SC.Enumerable 
+  @extends SC.Enumerable
   @extends SC.Observable
   @extends SC.Copyable
   @extends SC.Freezable
   @since SproutCore 1.0
 */
-SC.IndexSet = SC.mixin({}, 
+SC.IndexSet = SC.mixin({},
   SC.Enumerable, SC.Observable, SC.Freezable, SC.Copyable,
 /** @scope SC.IndexSet.prototype */ {
 
@@ -68,24 +68,26 @@ SC.IndexSet = SC.mixin({},
     this._hint(0, cur, ret); // hints are not copied manually - add them
     return ret ;
   },
-  
+
   /**
     To create a set, pass either a start and index or another IndexSet.
-    
+
+    @param {Number} start
+    @param {Number} length
     @returns {SC.IndexSet}
   */
-  create: function(start, length) { 
+  create: function(start, length) {
     var ret = SC.beget(this);
     ret.initObservable();
     ret.registerDependentKey('min', '[]');
-    
+
     // optimized method to clone an index set.
     if (start && start.isIndexSet) {
       ret._content = this._sc_sliceContent(start._content);
       ret.max = start.max;
-      ret.length = start.length; 
+      ret.length = start.length;
       ret.source = start.source ;
-      
+
     // otherwise just do a regular add
     } else {
       ret._content = [0];
@@ -96,71 +98,71 @@ SC.IndexSet = SC.mixin({},
 
   /**
     Walk like a duck.
-    
-    @property {Boolean}
+
+    @type Boolean
   */
   isIndexSet: YES,
 
-  /**  @private 
+  /**  @private
     Internal setting determines the preferred skip size for hinting sets.
-    
-    @property {Number}
+
+    @type Number
   */
   HINT_SIZE: 256,
-  
+
   /**
     Total number of indexes contained in the set
 
-    @property {Number}
+    @type Number
   */
   length: 0,
-  
+
   /**
-    One greater than the largest index currently stored in the set.  This 
+    One greater than the largest index currently stored in the set.  This
     is sometimes useful when determining the total range of items covering
     the index set.
-    
-    @property {Number}
+
+    @type Number
   */
   max: 0,
-  
+
   /**
     The first index included in the set or -1.
-    
-    @property {Number}
+
+    @type Number
   */
-  min: function() {  
-    var content = this._content, 
+  min: function() {
+    var content = this._content,
         cur = content[0];
     return (cur === 0) ? -1 : (cur>0) ? 0 : Math.abs(cur);
-    
+
   }.property('[]').cacheable(),
-  
+
   /**
     Returns the first index in the set .
-    
-    @property {Number}
+
+    @type Number
   */
   firstObject: function() {
-    return (this.get('length')>0) ? this.get('min') : undefined;  
+    return (this.get('length')>0) ? this.get('min') : undefined;
   }.property(),
-  
-  /** 
-    Returns the starting index of the nearest range for the specified 
+
+  /**
+    Returns the starting index of the nearest range for the specified
     index.
-    
+
     @param {Number} index
     @returns {Number} starting index
   */
-  rangeStartForIndex: function(index) {    
+  rangeStartForIndex: function(index) {
     var content = this._content,
         max     = this.get('max'),
         ret, next, accel;
-    
+
     // fast cases
     if (index >= max) return max ;
     if (Math.abs(content[index]) > index) return index ; // we hit a border
-    
+
     // use accelerator to find nearest content range
     accel = index - (index % SC.IndexSet.HINT_SIZE);
     ret = content[accel];
@@ -175,16 +177,16 @@ SC.IndexSet = SC.mixin({},
     }
     return ret ;
   },
-    
+
   /**
-    Returns YES if the passed index set contains the exact same indexes as 
+    Returns YES if the passed index set contains the exact same indexes as
     the receiver.  If you pass any object other than an index set, returns NO.
-    
+
     @param {Object} obj another object.
     @returns {Boolean}
   */
   isEqual: function(obj) {
-    
+
     // optimize for some special cases
     if (obj === this) return YES ;
     if (!obj || !obj.isIndexSet || (obj.max !== this.max) || (obj.length !== this.length)) return NO;
@@ -194,7 +196,7 @@ SC.IndexSet = SC.mixin({},
         rcontent = obj._content,
         cur      = 0,
         next     = lcontent[cur];
-    
+
     do {
       if (rcontent[cur] !== next) return NO ;
       cur = Math.abs(next) ;
@@ -202,20 +204,20 @@ SC.IndexSet = SC.mixin({},
     } while (cur !== 0);
     return YES ;
   },
-  
+
   /**
-    Returns the first index in the set before the passed index or null if 
+    Returns the first index in the set before the passed index or null if
     there are no previous indexes in the set.
-    
+
     @param {Number} index index to check
     @returns {Number} index or -1
   */
   indexBefore: function(index) {
-    
+
     if (index===0) return -1; // fast path
     index--; // start with previous index
-    
-    var content = this._content, 
+
+    var content = this._content,
         max     = this.get('max'),
         start   = this.rangeStartForIndex(index);
     if (!content) return null;
@@ -226,14 +228,14 @@ SC.IndexSet = SC.mixin({},
       index = start -1 ;
       start = this.rangeStartForIndex(index);
     }
-    
+
     return index;
   },
 
   /**
-    Returns the first index in the set after the passed index or null if 
+    Returns the first index in the set after the passed index or null if
     there are no additional indexes in the set.
-    
+
     @param {Number} index index to check
     @returns {Number} index or -1
   */
@@ -243,7 +245,7 @@ SC.IndexSet = SC.mixin({},
         start, next ;
     if (!content || (index>=max)) return -1; // fast path
     index++; // start with next index
-    
+
 
     // loop forwards until we find a range that is in the set.
     start = this.rangeStartForIndex(index);
@@ -253,27 +255,27 @@ SC.IndexSet = SC.mixin({},
       index = start = Math.abs(next);
       next  = content[start];
     }
-    
+
     return index;
   },
-  
+
   /**
     Returns YES if the index set contains the named index
-    
+
     @param {Number} start index or range
     @param {Number} length optional range length
     @returns {Boolean}
   */
   contains: function(start, length) {
     var content, cur, next, rstart, rnext;
-    
+
     // normalize input
-    if (length === undefined) { 
+    if (length === undefined) {
       if (start === null || start === undefined) return NO ;
-      
+
       if (typeof start === SC.T_NUMBER) {
         length = 1 ;
-        
+
       // if passed an index set, check each receiver range
       } else if (start && start.isIndexSet) {
         if (start === this) return YES ; // optimization
@@ -287,35 +289,35 @@ SC.IndexSet = SC.mixin({},
           next = content[cur];
         }
         return YES ;
-        
+
       } else {
-        length = start.length; 
+        length = start.length;
         start = start.start;
       }
     }
-    
+
     rstart = this.rangeStartForIndex(start);
     rnext  = this._content[rstart];
-    
+
     return (rnext>0) && (rstart <= start) && (rnext >= (start+length));
   },
 
   /**
     Returns YES if the index set contains any of the passed indexes.  You
     can pass a single index, a range or an index set.
-    
+
     @param {Number} start index, range, or IndexSet
     @param {Number} length optional range length
     @returns {Boolean}
   */
   intersects: function(start, length) {
     var content, cur, next, lim;
-    
+
     // normalize input
-    if (length === undefined) { 
+    if (length === undefined) {
       if (typeof start === SC.T_NUMBER) {
         length = 1 ;
-        
+
       // if passed an index set, check each receiver range
       } else if (start && start.isIndexSet) {
         if (start === this) return YES ; // optimization
@@ -329,13 +331,13 @@ SC.IndexSet = SC.mixin({},
           next = content[cur];
         }
         return NO ;
-        
+
       } else {
-        length = start.length; 
+        length = start.length;
         start = start.start;
       }
     }
-    
+
     cur     = this.rangeStartForIndex(start);
     content = this._content;
     next    = content[cur];
@@ -352,7 +354,7 @@ SC.IndexSet = SC.mixin({},
   /**
     Returns a new IndexSet without the passed range or indexes.   This is a
     convenience over simply cloning and removing.  Does some optimizations.
-    
+
     @param {Number} start index, range, or IndexSet
     @param {Number} length optional range length
     @returns {SC.IndexSet} new index set
@@ -361,17 +363,17 @@ SC.IndexSet = SC.mixin({},
     if (start === this) return SC.IndexSet.create(); // just need empty set
     return this.clone().remove(start, length);
   },
-  
+
   /**
     Replace the index set's current content with the passed index set.  This
     is faster than clearing the index set adding the values again.
-    
+
     @param {Number} start index, Range, or another IndexSet
-    @param {Number} length optional length of range. 
+    @param {Number} length optional length of range.
     @returns {SC.IndexSet} receiver
   */
   replace: function(start, length) {
-    
+
     if (length === undefined) {
       if (typeof start === SC.T_NUMBER) {
         length = 1 ;
@@ -384,39 +386,39 @@ SC.IndexSet = SC.mixin({},
           .enumerableContentDidChange()
         .endPropertyChanges();
         return this ;
-        
+
       } else {
         length = start.length;
         start  = start.start;
       }
     }
-    
+
     var oldlen = this.length;
     this._content.length=1;
     this._content[0] = 0;
     this.length = this.max = 0 ; // reset without notifying since add()
     return this.add(start, length);
   },
-  
+
   /**
     Adds the specified range of indexes to the set.  You can also pass another
     IndexSet to union the contents of the index set with the receiver.
-    
+
     @param {Number} start index, Range, or another IndexSet
-    @param {Number} length optional length of range. 
+    @param {Number} length optional length of range.
     @returns {SC.IndexSet} receiver
   */
   add: function(start, length) {
-    
+
     if (this.isFrozen) throw SC.FROZEN_ERROR;
-    
+
     var content, cur, next;
 
     // normalize IndexSet input
     if (start && start.isIndexSet) {
-      
+
       content = start._content;
-      
+
       if (!content) return this; // nothing to do
 
       cur = 0 ;
@@ -427,42 +429,42 @@ SC.IndexSet = SC.mixin({},
         next = content[cur];
       }
       return this ;
-      
-    } else if (length === undefined) { 
-      
+
+    } else if (length === undefined) {
+
       if (start === null || start === undefined) {
         return this; // nothing to do
       } else if (typeof start === SC.T_NUMBER) {
         length = 1 ;
       } else {
-        length = start.length; 
+        length = start.length;
         start = start.start;
       }
     } else if (length === null) length = 1 ;
 
     // if no length - do nothing.
     if (length <= 0) return this;
-    
+
     // special case - appending to end of set
     var max     = this.get('max'),
         oldmax  = max,
         delta, value ;
 
     content = this._content ;
-    
+
     if (start === max) {
 
       // if adding to the end and the end is in set, merge.
       if (start > 0) {
         cur = this.rangeStartForIndex(start-1);
         next = content[cur];
-        
+
         // just extend range at end
-        if (next > 0) { 
+        if (next > 0) {
           delete content[max]; // no 0
           content[cur] = max = start + length ;
           start = cur ;
-          
+
         // previous range was not in set, just tack onto the end
         } else {
           content[max] = max = start + length;
@@ -470,23 +472,23 @@ SC.IndexSet = SC.mixin({},
       } else {
         content[start] = max = length;
       }
-      
+
       content[max] = 0 ;
       this.set('max', max);
       this.set('length', this.length + length) ;
       length = max - start ;
-      
+
     } else if (start > max) {
       content[max] = 0-start; // empty!
       content[start] = start+length ;
       content[start+length] = 0; // set end
       this.set('max', start + length) ;
       this.set('length', this.length + length) ;
-      
+
       // affected range goes from starting range to end of content.
       length = start + length - max ;
       start = max ;
-      
+
     // otherwise, merge into existing range
     } else {
 
@@ -502,17 +504,17 @@ SC.IndexSet = SC.mixin({},
         cur = this.rangeStartForIndex(start-1);
         next = content[cur] ;
       }
-      
+
       // previous range is not in set.  splice it here
-      if (next < 0) { 
+      if (next < 0) {
         content[cur] = 0-start ;
-        
+
         // if previous range extends beyond this range, splice afterwards also
         if (Math.abs(next) > max) {
           content[start] = 0-max;
           content[max] = next ;
         } else content[start] = next;
-        
+
       // previous range is in set.  merge the ranges
       } else {
         start = cur ;
@@ -521,7 +523,7 @@ SC.IndexSet = SC.mixin({},
           max = next ;
         }
       }
-      
+
       // at this point there should be clean starting point for the range.
       // just walk the ranges, adding up the length delta and then removing
       // the range until we find a range that passes last
@@ -541,7 +543,7 @@ SC.IndexSet = SC.mixin({},
             next = max ;
           }
 
-          // ok, cur range is entirely inside top range.  
+          // ok, cur range is entirely inside top range.
           // add to delta if needed
           if (value < 0) delta += next - cur ;
         }
@@ -549,11 +551,11 @@ SC.IndexSet = SC.mixin({},
         delete content[cur] ; // and remove range
         cur = next;
       }
-      
+
       // cur should always === last now.  if the following range is in set,
       // merge in also - don't adjust delta because these aren't new indexes
       if ((cur = content[max]) > 0) {
-        delete content[max];     
+        delete content[max];
         max = cur ;
       }
 
@@ -563,11 +565,11 @@ SC.IndexSet = SC.mixin({},
 
       // adjust length
       this.set('length', this.get('length') + delta);
-      
+
       // compute hint range
       length = max - start ;
     }
-    
+
     this._hint(start, length);
     if (delta !== 0) this.enumerableContentDidChange();
     return this;
@@ -575,36 +577,36 @@ SC.IndexSet = SC.mixin({},
 
   /**
     Removes the specified range of indexes from the set
-    
+
     @param {Number} start index, Range, or IndexSet
-    @param {Number} length optional length of range. 
+    @param {Number} length optional length of range.
     @returns {SC.IndexSet} receiver
   */
   remove: function(start, length) {
 
     if (this.isFrozen) throw SC.FROZEN_ERROR;
-    
+
     // normalize input
-    if (length === undefined) { 
+    if (length === undefined) {
       if (start === null || start === undefined) {
         return this; // nothing to do
 
       } else if (typeof start === SC.T_NUMBER) {
         length = 1 ;
-      
+
       // if passed an index set, just add each range in the index set.
       } else if (start.isIndexSet) {
         start.forEachRange(this.remove, this);
         return this;
 
       } else {
-        length = start.length; 
+        length = start.length;
         start = start.start;
       }
     }
 
     if (length <= 0) return this; // nothing to do
-    
+
     // special case - appending to end of set
     var max     = this.get('max'),
         oldmax  = max,
@@ -626,17 +628,17 @@ SC.IndexSet = SC.mixin({},
       cur = this.rangeStartForIndex(start-1);
       next = content[cur] ;
     }
-    
+
     // previous range is in set.  splice it here
-    if (next > 0) { 
+    if (next > 0) {
       content[cur] = start ;
-      
+
       // if previous range extends beyond this range, splice afterwards also
       if (next > last) {
         content[start] = last;
         content[last] = next ;
       } else content[start] = next;
-      
+
     // previous range is not in set.  merge the ranges
     } else {
       start = cur ;
@@ -645,7 +647,7 @@ SC.IndexSet = SC.mixin({},
         last = next ;
       }
     }
-    
+
     // at this point there should be clean starting point for the range.
     // just walk the ranges, adding up the length delta and then removing
     // the range until we find a range that passes last
@@ -665,7 +667,7 @@ SC.IndexSet = SC.mixin({},
           next = last ;
         }
 
-        // ok, cur range is entirely inside top range.  
+        // ok, cur range is entirely inside top range.
         // add to delta if needed
         if (value > 0) delta += next - cur ;
       }
@@ -673,11 +675,11 @@ SC.IndexSet = SC.mixin({},
       delete content[cur] ; // and remove range
       cur = next;
     }
-    
+
     // cur should always === last now.  if the following range is not in set,
     // merge in also - don't adjust delta because these aren't new indexes
     if ((cur = content[last]) < 0) {
-      delete content[last];     
+      delete content[last];
       last = Math.abs(cur) ;
     }
 
@@ -686,42 +688,42 @@ SC.IndexSet = SC.mixin({},
       delete content[last];
       content[start] = 0 ;
       this.set('max', start); //max has changed
-      
+
     } else {
       content[start] = 0-last ;
     }
 
     // adjust length
     this.set('length', this.get('length') - delta);
-    
+
     // compute hint range
     length = last - start ;
-    
+
     this._hint(start, length);
     if (delta !== 0) this.enumerableContentDidChange();
     return this;
   },
-    
-  /** @private 
-    iterates through a named range, setting hints every HINT_SIZE indexes 
+
+  /** @private
+    iterates through a named range, setting hints every HINT_SIZE indexes
     pointing to the nearest range start.  The passed range must start on a
     range boundary.  It can end anywhere.
   */
   _hint: function(start, length, content) {
     if (content === undefined) content = this._content;
-    
+
     var skip    = SC.IndexSet.HINT_SIZE,
         next    = Math.abs(content[start]), // start of next range
         loc     = start - (start % skip) + skip, // next hint loc
         lim     = start + length ; // stop
-        
+
     while (loc < lim) {
       // make sure we are in current rnage
       while ((next !== 0) && (next <= loc)) {
-        start = next ; 
+        start = next ;
         next  = Math.abs(content[start]) ;
       }
-      
+
       // past end
       if (next === 0) {
         delete content[loc];
@@ -730,26 +732,28 @@ SC.IndexSet = SC.mixin({},
       } else if (loc !== start) {
         content[loc] = start ;  // set hint
       }
-      
+
       loc += skip;
     }
   },
 
   /**
-    Clears the set 
+    Clears the set
   */
   clear: function() {
     if (this.isFrozen) throw SC.FROZEN_ERROR;
-    
+
     var oldlen = this.length;
     this._content.length=1;
     this._content[0] = 0;
     this.set('length', 0).set('max', 0);
     if (oldlen > 0) this.enumerableContentDidChange();
   },
-  
+
   /**
     Add all the ranges in the passed array.
+
+    @param {Enumerable} objects The list of ranges you want to add
   */
   addEach: function(objects) {
     if (this.isFrozen) throw SC.FROZEN_ERROR;
@@ -762,41 +766,43 @@ SC.IndexSet = SC.mixin({},
       objects.forEach(function(idx) { this.add(idx); }, this);
     }
     this.endPropertyChanges();
-    
+
     return this ;
-  },  
+  },
 
   /**
     Removes all the ranges in the passed array.
+
+    @param {Object...} objects The list of objects you want to remove
   */
   removeEach: function(objects) {
     if (this.isFrozen) throw SC.FROZEN_ERROR;
 
     this.beginPropertyChanges();
-    
+
     var idx = objects.get('length') ;
     if (objects.isSCArray) {
       while(--idx >= 0) this.remove(objects.objectAt(idx)) ;
     } else if (objects.isEnumerable) {
-      objects.forEach(function(idx) { this.remove(idx); }, this); 
+      objects.forEach(function(idx) { this.remove(idx); }, this);
     }
-    
+
     this.endPropertyChanges();
-    
+
     return this ;
-  },  
+  },
 
   /**
-   Clones the set into a new set.  
+   Clones the set into a new set.
   */
   clone: function() {
-    return SC.IndexSet.create(this);    
+    return SC.IndexSet.create(this);
   },
-  
+
   /**
     Returns a string describing the internal range structure.  Useful for
     debugging.
-    
+
     @returns {String}
   */
   inspect: function() {
@@ -805,28 +811,26 @@ SC.IndexSet = SC.mixin({},
         idx     = 0,
         ret     = [],
         item;
-    
+
     for(idx=0;idx<len;idx++) {
       item = content[idx];
-      if (item !== undefined) ret.push("%@:%@".fmt(idx,item));      
+      if (item !== undefined) ret.push("%@:%@".fmt(idx,item));
     }
     return "SC.IndexSet<%@>".fmt(ret.join(' , '));
   },
-  
-  /** 
-    Invoke the callback, passing each occuppied range instead of each 
+
+  /**
+    Invoke the callback, passing each occuppied range instead of each
     index.  This can be a more efficient way to iterate in some cases.  The
     callback should have the signature:
-    
-    {{{
-      callback(start, length, indexSet, source) { ... }
-    }}}
-    
+
+          callback(start, length, indexSet, source) { ... }
+
     If you pass a target as a second option, the callback will be called in
     the target context.
-    
-    @param {Function} callback the iterator callback
-    @param {Object} target the target
+
+    @param {Function} callback The method to run on each iteration
+    @param {Object} target the object to call the callback on
     @returns {SC.IndexSet} receiver
   */
   forEachRange: function(callback, target) {
@@ -841,14 +845,14 @@ SC.IndexSet = SC.mixin({},
       cur  = Math.abs(next);
       next = content[cur];
     }
-    
+
     return this ;
-  },    
-  
+  },
+
   /**
     Invokes the callback for each index within the passed start/length range.
     Otherwise works just like regular forEach().
-    
+
     @param {Number} start starting index
     @param {Number} length length of range
     @param {Function} callback
@@ -865,11 +869,11 @@ SC.IndexSet = SC.mixin({},
 
     if (target === undefined) target = null ;
     while (next !== 0) {
-      if (cur < start) cur = start ; // skip forward 
-      while((cur < next) && (cur < lim)) { 
-        callback.call(target, cur++, idx++, this, source); 
+      if (cur < start) cur = start ; // skip forward
+      while((cur < next) && (cur < lim)) {
+        callback.call(target, cur++, idx++, this, source);
       }
-      
+
       if (cur >= lim) {
         cur = next = 0 ;
       } else {
@@ -882,7 +886,7 @@ SC.IndexSet = SC.mixin({},
 
   /**
     Total number of indexes within the specified range.
-    
+
     @param {Number|SC.IndexSet} start index, range object or IndexSet
     @param {Number} length optional range length
     @returns {Number} count of indexes
@@ -890,31 +894,31 @@ SC.IndexSet = SC.mixin({},
   lengthIn: function(start, length) {
 
     var ret = 0 ;
-    
+
     // normalize input
-    if (length === undefined) { 
+    if (length === undefined) {
       if (start === null || start === undefined) {
         return 0; // nothing to do
 
       } else if (typeof start === SC.T_NUMBER) {
         length = 1 ;
-        
+
       // if passed an index set, just add each range in the index set.
       } else if (start.isIndexSet) {
-        start.forEachRange(function(start, length) { 
+        start.forEachRange(function(start, length) {
           ret += this.lengthIn(start, length);
         }, this);
         return ret;
-        
+
       } else {
-        length = start.length; 
+        length = start.length;
         start = start.start;
       }
     }
 
     // fast path
     if (this.get('length') === 0) return 0;
-    
+
     var content = this._content,
         cur     = 0,
         next    = content[cur],
@@ -927,62 +931,62 @@ SC.IndexSet = SC.mixin({},
       cur  = Math.abs(next);
       next = content[cur];
     }
-    
+
     return ret ;
   },
-  
+
   // ..........................................................
   // OBJECT API
-  // 
-  
+  //
+
   /**
-    Optionally set the source property on an index set and then you can 
+    Optionally set the source property on an index set and then you can
     iterate over the actual object values referenced by the index set.  See
     indexOf(), lastIndexOf(), forEachObject(), addObject() and removeObject().
   */
   source: null,
-  
+
   /**
     Returns the first index in the set that matches the passed object.  You
     must have a source property on the set for this to work.
-    
-    @param {Object} object the object to check 
+
+    @param {Object} object the object to check
     @param {Number} startAt optional starting point
     @returns {Number} found index or -1 if not in set
   */
   indexOf: function(object, startAt) {
     var source  = this.source;
     if (!source) throw "%@.indexOf() requires source".fmt(this);
-    
+
     var len     = source.get('length'),
-        
+
         // start with the first index in the set
         content = this._content,
         cur     = content[0]<0 ? Math.abs(content[0]) : 0,
         idx ;
-        
+
     while(cur>=0 && cur<len) {
       idx = source.indexOf(object, cur);
       if (idx<0) return -1 ; // not found in source
       if (this.contains(idx)) return idx; // found in source and in set.
       cur = idx+1;
-    } 
-    
+    }
+
     return -1; // not found
   },
 
   /**
     Returns the last index in the set that matches the passed object.  You
     must have a source property on the set for this to work.
-    
-    @param {Object} object the object to check 
+
+    @param {Object} object the object to check
     @param {Number} startAt optional starting point
     @returns {Number} found index or -1 if not in set
   */
   lastIndexOf: function(object, startAt) {
     var source  = this.source;
     if (!source) throw "%@.lastIndexOf() requires source".fmt(this);
-    
+
     // start with the last index in the set
     var len     = source.get('length'),
         cur     = this.max-1,
@@ -994,26 +998,24 @@ SC.IndexSet = SC.mixin({},
       if (idx<0) return -1 ; // not found in source
       if (this.contains(idx)) return idx; // found in source and in set.
       cur = idx+1;
-    } 
-    
+    }
+
     return -1; // not found
   },
-  
+
   /**
     Iterates through the objects at each index location in the set.  You must
     have a source property on the set for this to work.  The callback you pass
     will be invoked for each object in the set with the following signature:
-    
-    {{{
-      function callback(object, index, source, indexSet) { ... }
-    }}}
-    
+
+          function callback(object, index, source, indexSet) { ... }
+
     If you pass a target, it will be used when the callback is called.
-    
-    @param {Function} callback function to invoke.  
+
+    @param {Function} callback function to invoke.
     @param {Object} target optional content. otherwise uses window
     @returns {SC.IndexSet} receiver
-  */ 
+  */
   forEachObject: function(callback, target) {
     var source  = this.source;
     if (!source) throw "%@.forEachObject() requires source".fmt(this);
@@ -1022,30 +1024,32 @@ SC.IndexSet = SC.mixin({},
         cur     = 0,
         idx     = 0,
         next    = content[cur];
-        
+
     if (target === undefined) target = null ;
     while (next !== 0) {
-      
-      while(cur < next) { 
-        callback.call(target, source.objectAt(cur), cur, source, this); 
+
+      while(cur < next) {
+        callback.call(target, source.objectAt(cur), cur, source, this);
         cur++;
       }
-      
+
       cur  = Math.abs(next);
       next = content[cur];
     }
     return this ;
   },
-  
+
   /**
-    Adds all indexes where the object appears to the set.  If firstOnly is 
+    Adds all indexes where the object appears to the set.  If firstOnly is
     passed, then it will find only the first index and add it.  If  you know
     the object only appears in the source array one time, firstOnly may make
     this method faster.
-    
+
     Requires source to work.
-    
+
     @param {Object} object the object to add
+    @param {Boolean} firstOnly Set to true if you can assume that the first
+       match is the only one
     @returns {SC.IndexSet} receiver
   */
   addObject: function(object, firstOnly) {
@@ -1054,23 +1058,25 @@ SC.IndexSet = SC.mixin({},
 
     var len = source.get('length'),
         cur = 0, idx;
-        
+
     while(cur>=0 && cur<len) {
       idx = source.indexOf(object, cur);
-      if (idx >= 0) { 
+      if (idx >= 0) {
         this.add(idx);
         if (firstOnly) return this ;
         cur = idx++;
       } else return this ;
     }
-    return this ;    
+    return this ;
   },
 
   /**
-    Adds any indexes matching the passed objects.  If firstOnly is passed, 
+    Adds any indexes matching the passed objects.  If firstOnly is passed,
     then only finds the first index for each object.
-    
+
     @param {SC.Enumerable} objects the objects to add
+    @param {Boolean} firstOnly Set to true if you can assume that the first
+       match is the only one
     @returns {SC.IndexSet} receiver
   */
   addObjects: function(objects, firstOnly) {
@@ -1079,16 +1085,18 @@ SC.IndexSet = SC.mixin({},
     }, this);
     return this;
   },
-  
+
   /**
-    Removes all indexes where the object appears to the set.  If firstOnly is 
+    Removes all indexes where the object appears to the set.  If firstOnly is
     passed, then it will find only the first index and add it.  If  you know
     the object only appears in the source array one time, firstOnly may make
     this method faster.
-    
+
     Requires source to work.
-    
+
     @param {Object} object the object to add
+    @param {Boolean} firstOnly Set to true if you can assume that the first
+       match is the only one
     @returns {SC.IndexSet} receiver
   */
   removeObject: function(object, firstOnly) {
@@ -1097,23 +1105,25 @@ SC.IndexSet = SC.mixin({},
 
     var len = source.get('length'),
         cur = 0, idx;
-        
+
     while(cur>=0 && cur<len) {
       idx = source.indexOf(object, cur);
-      if (idx >= 0) { 
+      if (idx >= 0) {
         this.remove(idx);
         if (firstOnly) return this ;
         cur = idx+1;
       } else return this ;
     }
-    return this ;    
+    return this ;
   },
 
   /**
-    Removes any indexes matching the passed objects.  If firstOnly is passed, 
+    Removes any indexes matching the passed objects.  If firstOnly is passed,
     then only finds the first index for each object.
-    
+
     @param {SC.Enumerable} objects the objects to add
+    @param {Boolean} firstOnly Set to true if you can assume that the first
+       match is the only one
     @returns {SC.IndexSet} receiver
   */
   removeObjects: function(objects, firstOnly) {
@@ -1122,20 +1132,20 @@ SC.IndexSet = SC.mixin({},
     }, this);
     return this;
   },
-  
-  
+
+
   // .......................................
-  // PRIVATE 
+  // PRIVATE
   //
 
-  /** 
-    Usually observing notifications from IndexSet are not useful, so 
+  /**
+    Usually observing notifications from IndexSet are not useful, so
     supress them by default.
-    
-    @property {Boolean}
+
+    @type Boolean
   */
   LOG_OBSERVING: NO,
-  
+
   /** @private - optimized call to forEach() */
   forEach: function(callback, target) {
     var content = this._content,
@@ -1146,21 +1156,21 @@ SC.IndexSet = SC.mixin({},
 
     if (target === undefined) target = null ;
     while (next !== 0) {
-      while(cur < next) { 
-        callback.call(target, cur++, idx++, this, source); 
+      while(cur < next) {
+        callback.call(target, cur++, idx++, this, source);
       }
       cur  = Math.abs(next);
       next = content[cur];
     }
     return this ;
   },
-  
+
   /** @private - support iterators */
   nextObject: function(ignore, idx, context) {
     var content = this._content,
         next    = context.next,
         max     = this.get('max'); // next boundary
-    
+
     // seed.
     if (idx === null) {
       idx = next = 0 ;
@@ -1170,19 +1180,19 @@ SC.IndexSet = SC.mixin({},
       return null ; // nothing left to do
 
     } else idx++; // look on next index
-    
+
     // look for next non-empty range if needed.
     if (idx === next) {
-      do { 
+      do {
         idx = Math.abs(next);
         next = content[idx];
       } while(next < 0);
       context.next = next;
     }
-    
+
     return idx;
   },
-  
+
   toString: function() {
     var str = [];
     this.forEachRange(function(start, length) {
@@ -1190,7 +1200,7 @@ SC.IndexSet = SC.mixin({},
     }, this);
     return "SC.IndexSet<%@>".fmt(str.join(',')) ;
   },
-  
+
   max: 0
 
 }) ;