Add a --sort-order option

Valid values for the `--sort-order` flag are `"source"` (default) and
`"alpha"`. When set to `"alpa"` the order of the entries in the docs
are sorted alphabetically.

Fixes documentationjs#534

Author: arv

docs/USAGE.md

@@ -45,6 +45,8 @@ Options:
   --document-exported  Generate documentation for all exported bindings and
                        members even if there is no JSDoc for them
                                                       [boolean] [default: false]
+  --sort-order         The order to sort the documentation
+                                [choices: "source", "alpha"] [default: "source"]
   --theme, -t          specify a theme: this must be a valid theme module
   --name               project name. by default, inferred from package.json
   --watch, -w          watch input files and rebuild documentation when they

lib/commands/shared_options.js

@@ -59,6 +59,11 @@ function sharedInputOptions(parser) {
     describe: 'Generate documentation for all exported bindings and members ' +
       'even if there is no JSDoc for them',
     default: false
+  })
+  .option('sort-order', {
+    describe: 'The order to sort the documentation',
+    choices: ['source', 'alpha'],
+    default: 'source'
   });
 }
 

lib/sort.js

@@ -14,9 +14,7 @@ var chalk = require('chalk');
  */
 module.exports = function sortDocs(comments, options) {
   if (!options || !options.toc) {
-    return comments.sort(function (a, b) {
-      return a.context.sortKey.localeCompare(b.context.sortKey);
-    });
+    return sortComments(comments, options && options.sortOrder);
   }
   var indexes = options.toc.reduce(function (memo, val, i) {
     if (typeof val === 'object' && val.name) {
@@ -67,9 +65,7 @@ module.exports = function sortDocs(comments, options) {
       return indexes[a.name] - indexes[b.name];
     }
   });
-  unfixed.sort(function (a, b) {
-    return a.context.sortKey.localeCompare(b.context.sortKey);
-  });
+  sortComments(unfixed, options.sortOrder);
   Object.keys(toBeSorted).filter(function (key) {
     return toBeSorted[key] === false;
   }).forEach(function (key) {
@@ -78,3 +74,16 @@ module.exports = function sortDocs(comments, options) {
   });
   return fixed.concat(unfixed);
 };
+
+function compareCommentsByName(a, b) {
+  return a.name.localeCompare(b.name, undefined, {caseFirst: 'upper'});
+}
+
+function compareCommentsBySourceLocation(a, b) {
+  return a.context.sortKey.localeCompare(b.context.sortKey);
+}
+
+function sortComments(comments, sortOrder) {
+  return comments.sort(sortOrder === 'alpha' ?
+    compareCommentsByName : compareCommentsBySourceLocation);
+}

test/fixture/sort-order-alpha.input.js

@@ -0,0 +1,31 @@
+// Options: {"sortOrder": "alpha"}
+
+/** */
+function b() {}
+
+/** */
+function a() {}
+
+/** */
+class A {
+  /** */
+  y() {}
+  /** */
+  Y() {}
+  /** */
+  x() {}
+  /** */
+  X() {}
+}
+
+/** */
+class B {
+  /** */
+  y() {}
+  /** */
+  Y() {}
+  /** */
+  x() {}
+  /** */
+  X() {}
+}