Upgrade to ExtJS 4.0.7 - Released 10/19/2011

[extjs.git] / src / util / Sorter.js

diff --git a/src/util/Sorter.js b/src/util/Sorter.js
index aaa0f4d..c233df4 100644 (file)
--- a/src/util/Sorter.js
+++ b/src/util/Sorter.js
@@ -13,93 +13,91 @@ If you are unsure which license is appropriate for your use, please contact the
 
 */
 /**
- * @class Ext.util.Sorter
- * @extends Object
-
-Represents a single sorter that can be applied to a Store. The sorter is used
-to compare two values against each other for the purpose of ordering them. Ordering
-is achieved by specifying either:
-- {@link #property A sorting property}
-- {@link #sorterFn A sorting function} 
-
-As a contrived example, we can specify a custom sorter that sorts by rank:
-
-    Ext.define('Person', {
-        extend: 'Ext.data.Model',
-        fields: ['name', 'rank']
-    });
-
-    Ext.create('Ext.data.Store', {
-        model: 'Person',
-        proxy: 'memory',
-        sorters: [{
-            sorterFn: function(o1, o2){
-                var getRank = function(o){
-                    var name = o.get('rank');
-                    if (name === 'first') {
-                        return 1;
-                    } else if (name === 'second') {
-                        return 2;
-                    } else {
-                        return 3;
-                    }
-                },
-                rank1 = getRank(o1),
-                rank2 = getRank(o2);
-                
-                if (rank1 === rank2) {
-                    return 0;
-                }
-                
-                return rank1 < rank2 ? -1 : 1;
-            }
-        }],
-        data: [{
-            name: 'Person1',
-            rank: 'second'
-        }, {
-            name: 'Person2',
-            rank: 'third'
-        }, {
-            name: 'Person3',
-            rank: 'first'
-        }] 
-    });
-
- * @markdown
+ * Represents a single sorter that can be applied to a Store. The sorter is used
+ * to compare two values against each other for the purpose of ordering them. Ordering
+ * is achieved by specifying either:
+ *
+ * - {@link #property A sorting property}
+ * - {@link #sorterFn A sorting function}
+ *
+ * As a contrived example, we can specify a custom sorter that sorts by rank:
+ *
+ *     Ext.define('Person', {
+ *         extend: 'Ext.data.Model',
+ *         fields: ['name', 'rank']
+ *     });
+ *
+ *     Ext.create('Ext.data.Store', {
+ *         model: 'Person',
+ *         proxy: 'memory',
+ *         sorters: [{
+ *             sorterFn: function(o1, o2){
+ *                 var getRank = function(o){
+ *                     var name = o.get('rank');
+ *                     if (name === 'first') {
+ *                         return 1;
+ *                     } else if (name === 'second') {
+ *                         return 2;
+ *                     } else {
+ *                         return 3;
+ *                     }
+ *                 },
+ *                 rank1 = getRank(o1),
+ *                 rank2 = getRank(o2);
+ *
+ *                 if (rank1 === rank2) {
+ *                     return 0;
+ *                 }
+ *
+ *                 return rank1 < rank2 ? -1 : 1;
+ *             }
+ *         }],
+ *         data: [{
+ *             name: 'Person1',
+ *             rank: 'second'
+ *         }, {
+ *             name: 'Person2',
+ *             rank: 'third'
+ *         }, {
+ *             name: 'Person3',
+ *             rank: 'first'
+ *         }]
+ *     });
  */
 Ext.define('Ext.util.Sorter', {
 
     /**
-     * @cfg {String} property The property to sort by. Required unless {@link #sorterFn} is provided.
-     * The property is extracted from the object directly and compared for sorting using the built in
-     * comparison operators.
+     * @cfg {String} property
+     * The property to sort by. Required unless {@link #sorterFn} is provided. The property is extracted from the object
+     * directly and compared for sorting using the built in comparison operators.
      */
     
     /**
-     * @cfg {Function} sorterFn A specific sorter function to execute. Can be passed instead of {@link #property}.
-     * This sorter function allows for any kind of custom/complex comparisons.
-     * The sorterFn receives two arguments, the objects being compared. The function should return:
-     * <ul>
-     * <li>-1 if o1 is "less than" o2</li>
-     * <li>0 if o1 is "equal" to o2</li>
-     * <li>1 if o1 is "greater than" o2</li>
-     * </ul>
+     * @cfg {Function} sorterFn
+     * A specific sorter function to execute. Can be passed instead of {@link #property}. This sorter function allows
+     * for any kind of custom/complex comparisons. The sorterFn receives two arguments, the objects being compared. The
+     * function should return:
+     *
+     *   - -1 if o1 is "less than" o2
+     *   - 0 if o1 is "equal" to o2
+     *   - 1 if o1 is "greater than" o2
      */
     
     /**
-     * @cfg {String} root Optional root property. This is mostly useful when sorting a Store, in which case we set the
-     * root to 'data' to make the filter pull the {@link #property} out of the data object of each item
+     * @cfg {String} root
+     * Optional root property. This is mostly useful when sorting a Store, in which case we set the root to 'data' to
+     * make the filter pull the {@link #property} out of the data object of each item
      */
     
     /**
-     * @cfg {Function} transform A function that will be run on each value before
-     * it is compared in the sorter. The function will receive a single argument,
-     * the value.
+     * @cfg {Function} transform
+     * A function that will be run on each value before it is compared in the sorter. The function will receive a single
+     * argument, the value.
      */
     
     /**
-     * @cfg {String} direction The direction to sort by. Defaults to ASC
+     * @cfg {String} direction
+     * The direction to sort by.
      */
     direction: "ASC",
     
@@ -184,8 +182,8 @@ Ext.define('Ext.util.Sorter', {
     
     /**
      * Update the sort function for this sorter.
-     * @param {Function} fn (Optional) A new sorter function for this sorter. If not specified it will use the
-     * default sorting function.
+     * @param {Function} [fn] A new sorter function for this sorter. If not specified it will use the default
+     * sorting function.
      */
     updateSortFunction: function(fn) {
         var me = this;