generate docs

.verb.md

@@ -34,124 +34,110 @@ arraySort(array, comparisonArgs);
 ```
 
 - `array`: **{Array}** The array to sort
-- `comparisonArgs`: **{Function|String|Array}**: Any number of functions, object paths, or arrays or objects paths and functions may be passed.
+- `comparisonArgs`: **{Function|String|Array}**: One or more functions or object paths to use for sorting. 
 
 
 ## Examples
 
-### Object paths
-
-Say you have the following blog posts:
+**[Sort blog posts](examples/blog-posts.js)**
 
 ```js
-var collection = [
-  { path: 'a.md', locals: { date: '2014-01-09' } },
-  { path: 'f.md', locals: { date: '2014-01-02' } },
-  { path: 'd.md', locals: { date: '2013-05-06' } },
-  { path: 'e.md', locals: { date: '2015-01-02' } },
-  { path: 'b.md', locals: { date: '2012-01-02' } },
-  { path: 'f.md', locals: { date: '2014-06-01' } },
-  { path: 'c.md', locals: { date: '2015-04-12' } },
-  { path: 'g.md', locals: { date: '2014-02-02' } },
+var arraySort = require('{%= name %}');
+
+var posts = [
+  { path: 'c.md', locals: { date: '2014-01-09' } },
+  { path: 'a.md', locals: { date: '2014-01-02' } },
+  { path: 'b.md', locals: { date: '2013-05-06' } },
 ];
-```
 
-and you want to sort them by `locals.date`:
+// sort by `locals.date`
+console.log(arraySort(posts, 'locals.date'));
 
-```js
-arraySort(collection, 'locals.date');
+// sort by `path`
+console.log(arraySort(posts, 'path'));
 ```
 
-**Result**
+**[Sort by multiple properties](examples/multiple-props.js)**
 
 ```js
-[
-  { path: 'b.md', locals: { date: '2012-01-02' } },
-  { path: 'd.md', locals: { date: '2013-05-06' } },
-  { path: 'f.md', locals: { date: '2014-01-02' } },
-  { path: 'a.md', locals: { date: '2014-01-09' } },
-  { path: 'g.md', locals: { date: '2014-02-02' } },
-  { path: 'f.md', locals: { date: '2014-06-01' } },
-  { path: 'e.md', locals: { date: '2015-01-02' } },
-  { path: 'c.md', locals: { date: '2015-04-12' } }
-];
-```
-
-### Sort by multiple properties and functions
-
-Here are the "posts" we want to sort:
+var arraySort = require('{%= name %}');
 
-```js
 var posts = [
-  { path: 'a.md', locals: { date: '2014-01-01', foo: 'zzz', bar: 1 } },
-  { path: 'f.md', locals: { date: '2014-01-01', foo: 'mmm', bar: 2 } },
-  { path: 'd.md', locals: { date: '2014-01-01', foo: 'xxx', bar: 3 } },
-  { path: 'i.md', locals: { date: '2014-01-01', foo: 'xxx', bar: 5 } },
-  { path: 'k.md', locals: { date: '2014-01-01', foo: 'xxx', bar: 1 } },
-  { path: 'j.md', locals: { date: '2014-01-01', foo: 'xxx', bar: 4 } },
-  { path: 'h.md', locals: { date: '2014-01-01', foo: 'xxx', bar: 6 } },
-  { path: 'l.md', locals: { date: '2014-01-01', foo: 'xxx', bar: 7 } },
-  { path: 'e.md', locals: { date: '2015-01-02', foo: 'aaa', bar: 8 } },
-  { path: 'b.md', locals: { date: '2012-01-02', foo: 'ccc', bar: 9 } },
-  { path: 'f.md', locals: { date: '2014-06-01', foo: 'rrr', bar: 10 } },
-  { path: 'c.md', locals: { date: '2015-04-12', foo: 'ttt', bar: 11 } },
-  { path: 'g.md', locals: { date: '2014-02-02', foo: 'yyy', bar: 12 } },
+  { locals: { foo: 'bbb', date: '2013-05-06' }},
+  { locals: { foo: 'aaa', date: '2012-01-02' }},
+  { locals: { foo: 'ccc', date: '2014-01-02' }},
+  { locals: { foo: 'ccc', date: '2015-01-02' }},
+  { locals: { foo: 'bbb', date: '2014-06-01' }},
+  { locals: { foo: 'aaa', date: '2014-02-02' }},
 ];
-```
 
-**The goal**
+// sort by `locals.foo`, then `locals.date`
+var result = arraySort(posts, ['locals.foo', 'locals.date']);
 
-Sort "posts" by the following:
+console.log(result);
+// [ { locals: { foo: 'aaa', date: '2012-01-02' } },
+//   { locals: { foo: 'aaa', date: '2014-02-02' } },
+//   { locals: { foo: 'bbb', date: '2013-05-06' } },
+//   { locals: { foo: 'bbb', date: '2014-06-01' } },
+//   { locals: { foo: 'ccc', date: '2014-01-02' } },
+//   { locals: { foo: 'ccc', date: '2015-01-02' } } ]
+```
 
-- `locals.date`: our first choice
-- `locals.foo`: Use this when mulitiple posts have the same `locals.date` value
-- `locals.bar`: Use this when mulitiple posts have the same `locals.foo` value
+**[Custom function](examples/custom-function.js)**
 
+If custom functions are supplied, array elements are sorted according to the return value of the compare function. See the [docs for `Array.sort()`][mozilla] for more details.
 
 ```js
-// let's create a reusable comparison function
-var compare = function(prop) { 
-  // the last arg, `fn` is the internal comparison function
-  // used by the lib. it's exposed here for convenience
-  return function (a, b, fn) {
-    var valA = get(a, prop);
-    var valB = get(b, prop);
-    return fn(valA, valB);
+var arr = [
+  {one: 'w', two: 'b'},
+  {one: 'z', two: 'a'},
+  {one: 'x', two: 'c'},
+  {one: 'y', two: 'd'},
+];
+
+function compare(prop) {
+  return function (a, b) {
+    return a[prop].localeCompare(b[prop]);
   };
-};
-```
+}
 
-**Time to sort!**
+var result = arraySort(arr, function (a, b) {
+  return a.two.localeCompare(b.two);
+});
 
-```js
-// the comparison args can be an array or a list, makes no difference
-arraySort(posts, ['locals.date', compare('locals.foo'), compare('locals.bar')]);
+console.log(result);
+// [ { one: 'z', two: 'a' },
+//   { one: 'w', two: 'b' },
+//   { one: 'x', two: 'c' },
+//   { one: 'y', two: 'd' } ]
 ```
 
-**Result**
+**[Multiple custom functions](examples/custom-functions.js)**
 
 ```js
-[
-  { path: 'b.md', locals: { date: '2012-01-02', foo: 'ccc', bar: 9 } },
-  { path: 'f.md', locals: { date: '2014-01-01', foo: 'mmm', bar: 2 } },
-  { path: 'k.md', locals: { date: '2014-01-01', foo: 'xxx', bar: 1 } },
-  { path: 'd.md', locals: { date: '2014-01-01', foo: 'xxx', bar: 3 } },
-  { path: 'j.md', locals: { date: '2014-01-01', foo: 'xxx', bar: 4 } },
-  { path: 'i.md', locals: { date: '2014-01-01', foo: 'xxx', bar: 5 } },
-  { path: 'h.md', locals: { date: '2014-01-01', foo: 'xxx', bar: 6 } },
-  { path: 'l.md', locals: { date: '2014-01-01', foo: 'xxx', bar: 7 } },
-  { path: 'a.md', locals: { date: '2014-01-01', foo: 'zzz', bar: 1 } },
-  { path: 'g.md', locals: { date: '2014-02-02', foo: 'yyy', bar: 12 } },
-  { path: 'f.md', locals: { date: '2014-06-01', foo: 'rrr', bar: 10 } },
-  { path: 'e.md', locals: { date: '2015-01-02', foo: 'aaa', bar: 8 } },
-  { path: 'c.md', locals: { date: '2015-04-12', foo: 'ttt', bar: 11 } }
-]);
-```
+var arr = [
+  {foo: 'w', bar: 'y', baz: 'w'},
+  {foo: 'x', bar: 'y', baz: 'w'},
+  {foo: 'x', bar: 'y', baz: 'z'},
+  {foo: 'x', bar: 'x', baz: 'w'},
+];
 
-### Custom functions
+// reusable compare function
+function compare(prop) {
+  return function (a, b) {
+    return a[prop].localeCompare(b[prop]);
+  };
+}
 
-If custom functions are supplied, array elements are sorted according to the return value of the compare function. See the [docs for `Array.sort()`][mozilla].
+// the `compare` functions can be a list or array
+var result = arraySort(arr, compare('foo'), compare('bar'), compare('baz'));
 
+console.log(result);
+// [ { foo: 'w', bar: 'y', baz: 'w' },
+//   { foo: 'x', bar: 'x', baz: 'w' },
+//   { foo: 'x', bar: 'y', baz: 'w' },
+//   { foo: 'x', bar: 'y', baz: 'z' } ]
+```
 
 ## Related projects
 {%= related(verb.related.list, {remove: name}) %}