docs updates

andrewplummer · Mar 7, 2012 · ba7878b · ba7878b
1 parent acc1157
commit ba7878b
Show file tree

Hide file tree

Showing 3 changed files with 19 additions and 12 deletions.
diff --git a/docs/generator.rb b/docs/generator.rb
@@ -26,6 +26,7 @@ def get_html_parameters(str)
   str.gsub!(/<(.+?)>/, '<span class="required parameter">\1</span>')
   str.gsub!(/\[(.+?)\]/, '<span class="optional parameter">\1</span>')
   str.gsub!(/@date_format/, '<a target="_blank" href="/dates">dates</a>')
+  str.gsub!(/@array_sorting/, '<a target="_blank" href="/sorting">dates</a>')
   str.gsub!(/extended objects/, '<a target="_blank" href="/objects#extended_objects">extended objects</a>')
   str.gsub!(/Object\.extend\(\)/, '<a target="_blank" href="/objects#object_extend" class="monospace">Object.extend()</a>')
   str.gsub!(/%(.+?)%/, '<span class="code">\1</span>')

diff --git a/lib/core.js b/lib/core.js
@@ -226,7 +226,7 @@
    * @method is[Type](<obj>)
    * @returns Boolean
    * @short Returns true if <obj> is an object of that type.
-   * @extra %isObject% will return false on anything that is not an object literal, including instances of inherited classes. Note also that %isNaN% will ONLY return true if the object IS %NaN%. It does not mean the same as browser native %isNaN%, which returns true for anything that is "not a number". Type methods are available as instance methods on extended objects and when using Object.extend().
+   * @extra %isObject% will return false on anything that is not an object literal, including instances of inherited classes. Note also that %isNaN% will ONLY return true if the object IS %NaN%. It does not mean the same as browser native %isNaN%, which returns true for anything that is "not a number". Type methods are available as instance methods on extended objects.
    * @example
    *
    *   Object.isArray([1,2,3])            -> true
@@ -297,7 +297,7 @@
        * @method watch(<obj>, <prop>, <fn>)
        * @returns Nothing
        * @short Watches a property of <obj> and runs <fn> when it changes.
-       * @extra <fn> is passed three arguments: the property <prop>, the old value, and the new value. The return value of [fn] will be set as the new value. This method is useful for things such as validating or cleaning the value when it is set. Warning: this method WILL NOT work in browsers that don't support %Object.defineProperty%. This notably includes IE 8 and below, and Opera. This is the only method in Sugar that is not fully compatible with all browsers. %watch% is available as an instance method on extended objects and when using Object.extend().
+       * @extra <fn> is passed three arguments: the property <prop>, the old value, and the new value. The return value of [fn] will be set as the new value. This method is useful for things such as validating or cleaning the value when it is set. Warning: this method WILL NOT work in browsers that don't support %Object.defineProperty%. This notably includes IE 8 and below, and Opera. This is the only method in Sugar that is not fully compatible with all browsers. %watch% is available as an instance method on extended objects.
        * @example
        *
        *   Object.watch({ foo: 'bar' }, 'foo', function(prop, oldVal, newVal) {
@@ -367,7 +367,7 @@
      * @method each(<obj>, [fn])
      * @returns Object
      * @short Iterates over each property in <obj> calling [fn] on each iteration.
-     * @extra %each% is available as an instance method on extended objects and when using Object.extend().
+     * @extra %each% is available as an instance method on extended objects.
      * @example
      *
      *   Object.each({ broken:'wear' }, function(key, value) {
@@ -391,12 +391,12 @@
      * @method merge(<target>, <source>, [deep] = false, [resolve] = true)
      * @returns Merged object
      * @short Merges all the properties of <source> into <target>.
-     * @extra Merges are shallow unless [deep] is %true%. Properties of <source> will win in the case of conflicts, unless [resolve] is %false%. [resolve] can also be a function that resolves the conflict. In this case it will be passed 3 arguments, %key%, %targetVal%, and %sourceVal%, with the context set to <source>. This will allow you to solve conflict any way you want, ie. adding two numbers together, etc. %merge% is available as an instance method on extended objects and when using Object.extend().
+     * @extra Merges are shallow unless [deep] is %true%. Properties of <source> will win in the case of conflicts, unless [resolve] is %false%. [resolve] can also be a function that resolves the conflict. In this case it will be passed 3 arguments, %key%, %targetVal%, and %sourceVal%, with the context set to <source>. This will allow you to solve conflict any way you want, ie. adding two numbers together, etc. %merge% is available as an instance method on extended objects.
      * @example
      *
      *   Object.merge({a:1},{b:2}) -> { a:1, b:2 }
-     *   Object.merge({a:1},{a:2}, false) -> { a:1 }
-     +   Object.merge({a:1},{a:2}, function(key, a, b) {
+     *   Object.merge({a:1},{a:2}, false, false) -> { a:1 }
+     +   Object.merge({a:1},{a:2}, false, function(key, a, b) {
      *     return a + b;
      *   }); -> { a:3 }
      *   Object.extended({a:1}).merge({b:2}) -> { a:1, b:2 }
@@ -441,7 +441,7 @@
      * @method isEmpty(<obj>)
      * @returns Boolean
      * @short Returns true if <obj> is empty.
-     * @extra %isEmpty% is available as an instance method on extended objects and when using Object.extend().
+     * @extra %isEmpty% is available as an instance method on extended objects.
      * @example
      *
      *   Object.isEmpty({})          -> true
@@ -458,7 +458,7 @@
      * @method equal(<a>, <b>)
      * @returns Boolean
      * @short Returns true if <a> and <b> are equal.
-     * @extra %empty% is available as an instance method as "equals" (note the "s") on extended objects and when using Object.extend().
+     * @extra %empty% is available as an instance method as "equals" (note the "s") on extended objects.
      * @example
      *
      *   Object.equal({a:2}, {a:2}) -> true
@@ -474,7 +474,7 @@
      * @method values(<obj>, [fn])
      * @returns Array
      * @short Returns an array containing the values in <obj>. Optionally calls [fn] for each value.
-     * @extra Returned values are in no particular order. %values% is available as an instance method on extended objects and when using Object.extend().
+     * @extra Returned values are in no particular order. %values% is available as an instance method on extended objects.
      * @example
      *
      *   Object.values({ broken: 'wear' }) -> ['wear']
@@ -497,7 +497,7 @@
      * @method clone(<obj> = {}, [deep] = false)
      * @returns Cloned object
      * @short Creates a clone (copy) of <obj>.
-     * @extra Default is a shallow clone, unless [deep] is true. %clone% is available as an instance method on extended objects and when using Object.extend().
+     * @extra Default is a shallow clone, unless [deep] is true. %clone% is available as an instance method on extended objects.
      * @example
      *
      *   Object.clone({foo:'bar'})            -> { foo: 'bar' }
@@ -575,7 +575,7 @@
      * @method keys(<obj>, [fn])
      * @returns Array
      * @short Returns an array containing the keys in <obj>. Optionally calls [fn] for each key.
-     * @extra This method is provided for browsers that don't support it natively, and additionally is enhanced to accept the callback [fn]. Returned keys are in no particular order. %keys% is available as an instance method on extended objects and when using Object.extend().
+     * @extra This method is provided for browsers that don't support it natively, and additionally is enhanced to accept the callback [fn]. Returned keys are in no particular order. %keys% is available as an instance method on extended objects.
      * @example
      *
      *   Object.keys({ broken: 'wear' }) -> ['broken']

diff --git a/lib/dates.js b/lib/dates.js
@@ -2163,13 +2163,19 @@
   });
 
 
+
+  /***
+   * Number module
+   *
+   ***/
+
   number.extend({
 
      /***
      * @method duration([locale] = currentLocale)
      * @returns String
      * @short Takes the number as milliseconds and returns a unit-adjusted localized string.
-     * @extra This method is the same as %Date#relative% without the localized equivalent of "from now" or "ago". [locale] can be passed as the first (and only) parameter.
+     * @extra This method is the same as %Date#relative% without the localized equivalent of "from now" or "ago". [locale] can be passed as the first (and only) parameter. Note that this method is only available when the dates package is included.
      * @example
      *
      *   (500).duration() -> '500 milliseconds'