Source-sorting by default (#410)

* Source-sorting by default

Many changes

* Uses a new version of module-deps that exposes a sort key
  we use to sort documentation.
* Adds inference for methods in objects
* Groups events into a separate comment property

* Add jsdoc property. Refs #388 (comment)

* Namespaces and paths

* More powerful paths: paths now include name, kind, and scope
* comments now include a 'namespace' property with a formatted namespace

* Fix tests

* Re-ignore fonts

* Nix sourceKey from output

* Pin dependency versions

* Fix module-deps-sortable ref

* Update tests for right deps

Author: tmcw

index.js

@@ -118,7 +118,7 @@ module.exports = function (indexes, options, callback) {
                 options.github && github
               ))
               .filter(Boolean)
-              .sort(sort.bind(undefined, options.order)))));
+              .sort(sort))));
     } catch (e) {
       callback(e);
     }

lib/hierarchy.js

@@ -2,6 +2,17 @@
 
 var hasOwnProperty = Object.prototype.hasOwnProperty;
 
+function pick(n) {
+  var item = {
+    name: n.name,
+    kind: n.kind
+  };
+  if (n.scope) {
+    item.scope = n.scope;
+  }
+  return item;
+}
+
 /**
  * @param {Array<Object>} comments an array of parsed comments
  * @returns {Array<Object>} nested comments, with only root comments
@@ -101,9 +112,30 @@ module.exports = function (comments) {
           comment.members[scope] = node.members[scope];
         }
 
-        comment.path = path.map(function (n) {
-          return n.name;
-        }).concat(comment.name);
+        if (comment.members.instance.length) {
+          comment.members.events = comment.members.instance.filter(function (member) {
+            return member.kind === 'event';
+          });
+
+          comment.members.instance = comment.members.instance.filter(function (member) {
+            return member.kind !== 'event';
+          });
+        }
+
+
+        comment.path = path.map(pick).concat(pick(comment));
+
+        var scopeChars = {
+          instance: '#',
+          static: '.'
+        };
+
+        comment.namespace = comment.path.reduce(function (memo, part) {
+          if (part.kind === 'event') {
+            return memo + '.event:' + part.name;
+          }
+          return memo + (scopeChars[part.scope] || '') + part.name;
+        }, '');
 
         if (hasUndefinedParent) {
           var memberOfTag = comment.tags.filter(function (tag) {
@@ -121,6 +153,7 @@ module.exports = function (comments) {
           result.push(comment);
         }
       }
+
     }
 
     return result;

lib/infer/kind.js

@@ -48,6 +48,9 @@ module.exports = function () {
       } else if (t.isExpressionStatement(path)) {
         // module.exports = function() {}
         findKind(path.node.expression.right);
+      } else if (t.isProperty(path)) {
+        // { foo: function() {} }
+        findKind(path.node.value);
       }
     }
 

lib/inline_tokenizer.js

@@ -13,12 +13,13 @@ function makeTokenizer(type, regex) {
     }
 
     return eat(match[0])({
-      'type': type,
-      'url': match[1],
-      'title': null,
-      'children': [{
-        'type': 'text',
-        'value': match[2] || match[1]
+      type: type,
+      url: match[1],
+      title: null,
+      jsdoc: true,
+      children: [{
+        type: 'text',
+        value: match[2] || match[1]
       }]
     });
   };

lib/input/dependency.js

@@ -1,6 +1,6 @@
 'use strict';
 
-var mdeps = require('module-deps'),
+var mdeps = require('module-deps-sortable'),
   fs = require('fs'),
   path = require('path'),
   babelify = require('babelify'),

lib/output/json.js

@@ -15,6 +15,7 @@ module.exports = function (comments, opts, callback) {
 
   walk(comments, function (comment) {
     delete comment.errors;
+    delete comment.context.sortKey;
   });
 
   return callback(null, JSON.stringify(comments, null, 2));

lib/parsers/javascript.js

@@ -6,6 +6,14 @@ var babylon = require('babylon'),
   isJSDocComment = require('../../lib/is_jsdoc_comment'),
   parse = require('../../lib/parse');
 
+function leftPad(str, width) {
+  str = str.toString();
+  while (str.length < width) {
+    str = '0' + str;
+  }
+  return str;
+}
+
 /**
  * Receives a module-dep item,
  * reads the file, parses the JavaScript, and parses the JSDoc.
@@ -50,7 +58,8 @@ function parseJavaScript(data) {
         function parseComment(comment) {
           var context = {
             loc: extend({}, JSON.parse(JSON.stringify(path.node.loc))),
-            file: data.file
+            file: data.file,
+            sortKey: data.sortKey + ' ' + leftPad(path.node.loc.start.line, 8)
           };
           // Avoid visiting the same comment twice as a leading
           // and trailing node

lib/parsers/polyglot.js

@@ -18,7 +18,8 @@ function parsePolyglot(data) {
     .map(function (comment) {
       var context = {
         loc: extend({}, comment.loc),
-        file: data.file
+        file: data.file,
+        sortKey: data.file + ' ' + comment.loc.start.line
       };
       return parse(comment.value, comment.loc, context);
     });

lib/sort.js

@@ -1,49 +1,14 @@
 'use strict';
 
-/**
- * Given a comment, get its sorting key: this is either the comment's
- * name tag, or a hardcoded sorting index given by a user-provided
- * `order` array.
- *
- * @param {Object} comment parsed documentation object
- * @param {Array<string>} [order=[]] an optional list of namepaths
- * @returns {string} sortable key
- * @private
- */
-function getSortKey(comment, order) {
-  var key = comment.context.file + ':' + comment.context.loc.start.line || comment.name;
-
-  if (order && order.indexOf(key) !== -1) {
-    return order.indexOf(key);
-  }
-
-  return key;
-}
-
 /**
  * Sort two documentation objects, given an optional order object. Returns
  * a numeric sorting value that is compatible with stream-sort.
  *
- * @param {Array<string>} order an array of namepaths that will be sorted
- * in the order given.
  * @param {Object} a documentation object
  * @param {Object} b documentation object
  * @return {number} sorting value
  * @private
  */
-module.exports = function sortDocs(order, a, b) {
-  a = getSortKey(a, order);
-  b = getSortKey(b, order);
-
-  if (typeof a === 'number' && typeof b === 'number') {
-    return a - b;
-  }
-  if (typeof a === 'number') {
-    return -1;
-  }
-  if (typeof b === 'number') {
-    return 1;
-  }
-
-  return a.toLowerCase().localeCompare(b.toLowerCase());
+module.exports = function sortDocs(a, b) {
+  return a.context.sortKey.localeCompare(b.context.sortKey);
 };

package.json

@@ -22,8 +22,8 @@
     "debounce": "^1.0.0",
     "disparity": "^2.0.0",
     "doctrine": "^1.1.0",
-    "documentation-theme-default": "3.0.0-beta1",
-    "documentation-theme-utils": "^2.0.2",
+    "documentation-theme-default": "3.0.0",
+    "documentation-theme-utils": "^3.0.0",
     "events": "^1.1.0",
     "extend": "^3.0.0",
     "get-comments": "^1.0.1",
@@ -33,7 +33,7 @@
     "mdast-util-inject": "^1.1.0",
     "micromatch": "^2.1.6",
     "mime": "^1.3.4",
-    "module-deps": "^4.0.2",
+    "module-deps-sortable": "4.0.6",
     "parse-filepath": "^0.6.3",
     "remark": "^4.1.2",
     "remark-toc": "^3.0.0",