Superpowered sorting

Author: tmcw

index.js

@@ -101,6 +101,7 @@ module.exports = function (indexes, options, callback) {
       callback(null,
         filterAccess(options.access,
           hierarchy(
+            sort(
             inputs
               .filter(filterJS(options.extension, options.polyglot))
               .reduce(function (memo, file) {
@@ -117,8 +118,7 @@ module.exports = function (indexes, options, callback) {
                 nest,
                 options.github && github
               ))
-              .filter(Boolean)
-              .sort(sort))));
+              .filter(Boolean), options))));
     } catch (e) {
       callback(e);
     }

lib/sort.js

@@ -1,5 +1,12 @@
 'use strict';
 
+var remark = require('remark');
+var inlineTokenizer = require('./inline_tokenizer');
+
+function parseMarkdown(string) {
+  return remark.use(inlineTokenizer).parse(string);
+}
+
 /**
  * Sort two documentation objects, given an optional order object. Returns
  * a numeric sorting value that is compatible with stream-sort.
@@ -9,6 +16,45 @@
  * @return {number} sorting value
  * @private
  */
-module.exports = function sortDocs(a, b) {
-  return a.context.sortKey.localeCompare(b.context.sortKey);
+module.exports = function sortDocs(comments, options) {
+  if (!options.toc) {
+    return comments.sort(function (a, b) {
+      return a.context.sortKey.localeCompare(b.context.sortKey);
+    });
+  } else {
+    var indexes = options.toc.reduce(function (memo, val, i) {
+      if (typeof val === 'object' && val.name) {
+        val.kind = 'note';
+        memo[val.name] = i;
+      } else {
+        memo[val] = i;
+      }
+      return memo;
+    }, {});
+    var fixed = options.toc.filter(function (val) {
+      return typeof val === 'object' && val.name;
+    }).map(function (val) {
+      if (val.description) {
+        val.description = parseMarkdown(val.description);
+      }
+      return val;
+    });
+    var unfixed = [];
+    comments.forEach(function (comment) {
+      if (!comment.memberof && indexes[comment.name] !== undefined) {
+        fixed.push(comment);
+      } else {
+        unfixed.push(comment);
+      }
+    });
+    fixed.sort(function (a, b) {
+      if (indexes[a.name] !== undefined && indexes[b.name] !== undefined) {
+        return indexes[a.name] - indexes[b.name];
+      }
+    });
+    unfixed.sort(function (a, b) {
+      return a.context.sortKey.localeCompare(b.context.sortKey);
+    });
+    return fixed.concat(unfixed);
+  }
 };