fully document sort api method

patrickkunka · Dec 8, 2016 · 8f322f4 · 8f322f4
1 parent 3b03e7d
commit 8f322f4
Show file tree

Hide file tree

Showing 4 changed files with 45 additions and 9 deletions.
diff --git a/demos/mixitup.min.js b/demos/mixitup.min.js
diff --git a/dist/mixitup.js b/dist/mixitup.js
@@ -1,7 +1,7 @@
 /**!
  * MixItUp v3.0.0-beta
  * A high-performance, dependency-free library for animated filtering, sorting and more
- * Build f52f3ec0-2620-4eef-b696-36b09c0d3b4a
+ * Build 6b06fe81-4ea9-43cd-95ec-e53682227df3
  *
  * @copyright Copyright 2014-2016 KunkaLabs Limited.
  * @author    KunkaLabs Limited.
@@ -7812,7 +7812,7 @@
          * @instance
          * @since       2.0.0
          * @param       {(string|HTMLElement|Array.<HTMLElement>|mixitup.CommandFilter)} selector
-         *      Any valid CSS selector (i.e. `'.category-a'`), or the values `'all'` or `'none'`. The filter function also accepts a reference to single target element or a collection of target elements to show.
+         *      Any valid CSS selector (i.e. `'.category-a'`), or the values `'all'` or `'none'`. The filter method also accepts a reference to single target element or a collection of target elements to show.
          * @param       {boolean}   [animate=true]
          *      An optional boolean dictating whether the operation should animate, or occur syncronously with no animation. `true` by default.
          * @param       {function}  [callback=null]
@@ -7972,11 +7972,29 @@
          *         console.log(state.activeSort.order === 'random') // true
          *     });
          *
+         * @example <caption>Example 5: Sorting via an element collection</caption>
+         *
+         * var collection = Array.from(container.querySelectorAll('.mix'));
+         *
+         * // Swap the position of two elements in the collection:
+         *
+         * var temp = collection[1];
+         *
+         * collection[1] = collection[0];
+         * collection[0] = temp;
+         *
+         * // Pass the sorted collection to MixItUp
+         *
+         * mixer.sort(collection)
+         *     .then(function(state) {
+         *         console.log(state.targets[0] === collection[0]); // true
+         *     });
+         *
          * @public
          * @instance
          * @since       2.0.0
-         * @param       {string}    sortString
-         *      A valid sort string (e.g. `'default'`, `'published-date:asc'`, or `'random'`).
+         * @param       {(string|Array.<HTMLElement>}    sortString
+         *      A valid sort string (e.g. `'default'`, `'published-date:asc'`, or `'random'`). The sort method also accepts an array of all target elements in a user-defined order.
          * @param       {boolean}   [animate=true]
          *      An optional boolean dictating whether the operation should animate, or occur syncronously with no animation. `true` by default.
          * @param       {function}  [callback=null]

diff --git a/dist/mixitup.min.js b/dist/mixitup.min.js
diff --git a/src/mixer.js b/src/mixer.js
@@ -2985,7 +2985,7 @@ h.extend(mixitup.Mixer.prototype,
      * @instance
      * @since       2.0.0
      * @param       {(string|HTMLElement|Array.<HTMLElement>|mixitup.CommandFilter)} selector
-     *      Any valid CSS selector (i.e. `'.category-a'`), or the values `'all'` or `'none'`. The filter function also accepts a reference to single target element or a collection of target elements to show.
+     *      Any valid CSS selector (i.e. `'.category-a'`), or the values `'all'` or `'none'`. The filter method also accepts a reference to single target element or a collection of target elements to show.
      * @param       {boolean}   [animate=true]
      *      An optional boolean dictating whether the operation should animate, or occur syncronously with no animation. `true` by default.
      * @param       {function}  [callback=null]
@@ -3145,11 +3145,29 @@ h.extend(mixitup.Mixer.prototype,
      *         console.log(state.activeSort.order === 'random') // true
      *     });
      *
+     * @example <caption>Example 5: Sorting via an element collection</caption>
+     *
+     * var collection = Array.from(container.querySelectorAll('.mix'));
+     *
+     * // Swap the position of two elements in the collection:
+     *
+     * var temp = collection[1];
+     *
+     * collection[1] = collection[0];
+     * collection[0] = temp;
+     *
+     * // Pass the sorted collection to MixItUp
+     *
+     * mixer.sort(collection)
+     *     .then(function(state) {
+     *         console.log(state.targets[0] === collection[0]); // true
+     *     });
+     *
      * @public
      * @instance
      * @since       2.0.0
-     * @param       {string}    sortString
-     *      A valid sort string (e.g. `'default'`, `'published-date:asc'`, or `'random'`).
+     * @param       {(string|Array.<HTMLElement>}    sortString
+     *      A valid sort string (e.g. `'default'`, `'published-date:asc'`, or `'random'`). The sort method also accepts an array of all target elements in a user-defined order.
      * @param       {boolean}   [animate=true]
      *      An optional boolean dictating whether the operation should animate, or occur syncronously with no animation. `true` by default.
      * @param       {function}  [callback=null]