Nested hierarchy support

Author: jfirebaugh

lib/hierarchy.js

@@ -1,87 +1,128 @@
 'use strict';
 
-/**
- * Add paths to each comment, making it possible to generate permalinks
- * that differentiate between instance functions with the same name but
- * different `@memberof` values.
- *
- *     Person#say  // the instance method named "say."
- *     Person.say  // the static method named "say."
- *     Person~say  // the inner method named "say."
- *
- * @param {Object} comment the jsdoc comment
- * @param {Array<string>} prefix an array of strings representing names
- * @param {string} namepath the namepath so far
- * @returns {undefined} changes its input by reference.
- */
-function addPath(comment, prefix, namepath) {
-  comment.path = prefix.concat([comment.name]);
-  comment.members.instance.forEach(function (member) {
-    addPath(member, comment.path, comment.namepath);
-  });
-  comment.members.static.forEach(function (member) {
-    addPath(member, comment.path, namepath);
-  });
-}
-
 /**
  * @param {Array<Object>} comments an array of parsed comments
  * @returns {Array<Object>} nested comments, with only root comments
  * at the top level.
  */
-function inferHierarchy(comments) {
-  var nameIndex = {}, i;
-
-  // We're going to iterate comments in reverse to generate the memberships so
-  // to avoid reversing the sort order we reverse the array for the name index.
-  comments.reverse();
-
-  // First, create a fast lookup index of Namespace names
-  // that might be used in memberof tags, and let all objects
-  // have members
-  for (i = 0; i < comments.length; i++) {
-    nameIndex[comments[i].name] = comments[i];
-    comments[i].members = { instance: [], static: [] };
-  }
+module.exports = function (comments) {
+  var id = 0,
+    root = {
+      members: {
+        instance: {},
+        static: {}
+      }
+    };
 
-  for (i = comments.length - 1; i >= 0; i--) {
-    var comment = comments[i];
+  comments.forEach(function (comment) {
+    var path = [];
 
-    if (!comment.memberof) {
-      continue;
+    if (comment.memberof) {
+      // TODO: full namepath parsing
+      path = comment.memberof
+        .split('.')
+        .map(function (segment) {
+          return ['static', segment];
+        });
     }
 
-    var memberOfTag = comment.tags.filter(function (tag) {
-      return tag.title === 'memberof'
-    })[0];
-    var memberOfTagLineNumber = (memberOfTag && memberOfTag.lineNumber) || 0;
-
-    var parent = nameIndex[comment.memberof];
-
-    if (!parent) {
+    if (!comment.name) {
       comment.errors.push({
-        message: 'memberof reference to ' + comment.memberof + ' not found',
-        commentLineNumber: memberOfTagLineNumber
+        message: 'could not determine @name for hierarchy'
       });
-      continue;
     }
 
-    parent.members[comment.scope || 'static'].push(comment);
+    path.push([
+      comment.scope || 'static',
+      comment.name || ('unknown_' + id++)
+    ]);
 
-    // remove non-root nodes from the lowest level: these are reachable
-    // as members of other docs.
-    comments.splice(i, 1);
-  }
+    var node = root;
 
-  // Now the members are in the right order but the root comments are reversed
-  // so we reverse once more.
-  comments.reverse();
+    while (path.length) {
+      var segment = path.shift(),
+        scope = segment[0],
+        name = segment[1];
 
-  for (i = 0; i < comments.length; i++) {
-    addPath(comments[i], [], '');
-  }
+      if (!node.members[scope][name]) {
+        node.members[scope][name] = {
+          comments: [],
+          members: {
+            instance: {},
+            static: {}
+          }
+        };
+      }
+
+      node = node.members[scope][name];
+    }
+
+    node.comments.push(comment);
+  });
+
+  /*
+   * Massage the hierarchy into a format more suitable for downstream consumers:
+   *
+   * * Individual top-level scopes are collapsed to a single array
+   * * Members at intermediate nodes are copied over to the corresponding comments,
+   *   with multisignature comments allowed.
+   * * Intermediate nodes without corresponding comments indicate an undefined
+   *   @memberof reference. Emit an error, and reparent the offending comment to
+   *   the root.
+   * * Add paths to each comment, making it possible to generate permalinks
+   *   that differentiate between instance functions with the same name but
+   *   different `@memberof` values.
+   *
+   *     Person#say  // the instance method named "say."
+   *     Person.say  // the static method named "say."
+   *     Person~say  // the inner method named "say."
+   */
+  function toComments(nodes, root, hasUndefinedParent, path) {
+    var result = [], scope;
+
+    path = path || [];
+
+    for (var name in nodes) {
+      var node = nodes[name];
+
+      for (scope in node.members) {
+        node.members[scope] = toComments(node.members[scope], root || result,
+          !node.comments.length,
+          node.comments.length ? path.concat(node.comments[0]) : []);
+      }
+
+      for (var i = 0; i < node.comments.length; i++) {
+        var comment = node.comments[i];
+
+        comment.members = {};
+        for (scope in node.members) {
+          comment.members[scope] = node.members[scope];
+        }
 
-  return comments;
-}
+        comment.path = path.map(function (n) {
+          return n.name;
+        }).concat(comment.name);
+
+        if (hasUndefinedParent) {
+          var memberOfTag = comment.tags.filter(function (tag) {
+            return tag.title === 'memberof'
+          })[0];
+          var memberOfTagLineNumber = (memberOfTag && memberOfTag.lineNumber) || 0;
+
+          comment.errors.push({
+            message: '@memberof reference to ' + comment.memberof + ' not found',
+            commentLineNumber: memberOfTagLineNumber
+          });
+
+          root.push(comment);
+        } else {
+          result.push(comment);
+        }
+      }
+    }
+
+    return result;
+  }
 
-module.exports = inferHierarchy;
+  return toComments(root.members.static);
+};

test/fixture/factory.output.json

@@ -147,7 +147,7 @@
     },
     "errors": [
       {
-        "message": "memberof reference to chart not found",
+        "message": "@memberof reference to chart not found",
         "commentLineNumber": 0
       }
     ],

test/fixture/newline-in-description.output.json

@@ -39,6 +39,9 @@
       {
         "message": "type Number found, number is standard",
         "commentLineNumber": 2
+      },
+      {
+        "message": "could not determine @name for hierarchy"
       }
     ],
     "params": [

test/fixture/no-name.output.json

@@ -35,7 +35,11 @@
         }
       }
     },
-    "errors": [],
+    "errors": [
+      {
+        "message": "could not determine @name for hierarchy"
+      }
+    ],
     "params": [
       {
         "title": "param",

test/fixture/trailing-only.output.json

@@ -34,7 +34,11 @@
         }
       }
     },
-    "errors": [],
+    "errors": [
+      {
+        "message": "could not determine @name for hierarchy"
+      }
+    ],
     "returns": [
       {
         "title": "returns",

test/lib/hierarchy.js

@@ -2,7 +2,8 @@
 
 var test = require('tap').test,
   parse = require('../../lib/parsers/javascript'),
-  hierarchy = require('../../lib/hierarchy');
+  hierarchy = require('../../lib/hierarchy'),
+  _ = require('lodash');
 
 function toComments(fn, filename) {
   return parse({
@@ -16,7 +17,7 @@ function evaluate(fn, callback) {
 }
 
 test('hierarchy', function (t) {
-  var result = evaluate(function () {
+  var comments = evaluate(function () {
     /**
      * @name Class
      * @class
@@ -47,31 +48,103 @@ test('hierarchy', function (t) {
      */
   });
 
-  t.equal(result.length, 1);
+  t.deepEqual(_.pluck(comments, 'name'), ['Class']);
+
+  var classMembers = comments[0].members;
 
-  t.equal(result[0].members.static.length, 2);
-  t.deepEqual(result[0].members.static[0].path, ['Class', 'isClass']);
+  t.deepEqual(_.pluck(classMembers.static, 'name'), ['isClass', 'MAGIC_NUMBER']);
+  t.deepEqual(_.pluck(classMembers.instance, 'name'), ['getFoo', 'event']);
 
-  t.equal(result[0].members.instance.length, 2);
-  t.deepEqual(result[0].members.instance[0].path, ['Class', 'getFoo']);
-  t.deepEqual(result[0].members.instance[1].path, ['Class', 'event']);
+  t.deepEqual(classMembers.static[0].path, ['Class', 'isClass']);
+  t.deepEqual(classMembers.instance[0].path, ['Class', 'getFoo']);
+  t.deepEqual(classMembers.instance[1].path, ['Class', 'event']);
 
   t.end();
 });
 
+test('hierarchy - nesting', function (t) {
+  var comments = evaluate(function () {
+    /**
+     * @name Parent
+     * @class
+     */
+
+    /**
+     * @name enum
+     * @memberof Parent
+     */
+
+    /**
+     * @name Parent
+     * @memberof Parent.enum
+     */
+
+    /**
+     * @name Child
+     * @memberof Parent.enum
+     */
+  });
+
+  t.deepEqual(_.pluck(comments, 'name'), ['Parent']);
+
+  var classMembers = comments[0].members;
+  t.deepEqual(_.pluck(classMembers.static, 'name'), ['enum']);
+
+  var enumMembers = classMembers.static[0].members;
+  t.deepEqual(_.pluck(enumMembers.static, 'name'), ['Parent', 'Child']);
+  t.deepEqual(enumMembers.static[0].path, ['Parent', 'enum', 'Parent']);
+  t.deepEqual(enumMembers.static[1].path, ['Parent', 'enum', 'Child']);
+
+  t.end();
+});
+
+test('hierarchy - multisignature', function (t) {
+  var comments = evaluate(function () {
+    /**
+     * @name Parent
+     * @class
+     */
+
+    /**
+     * @name foo
+     * @memberof Parent
+     * @instance
+     */
+
+    /**
+     * @name foo
+     * @memberof Parent
+     * @instance
+     */
+  });
+
+  t.deepEqual(_.pluck(comments[0].members.instance, 'name'), ['foo', 'foo']);
+  t.end();
+});
+
 test('hierarchy - missing memberof', function (t) {
-  var result = evaluate(function () {
+  var test = evaluate(function () {
     /**
-     * Get foo
+     * @name test
      * @memberof DoesNotExist
-     * @returns {Number} foo
      */
-  });
+  })[0];
 
-  t.equal(result.length, 1);
-  t.deepEqual(result[0].errors[0], {
-    message: 'memberof reference to DoesNotExist not found',
+  t.deepEqual(test.errors, [{
+    message: '@memberof reference to DoesNotExist not found',
     commentLineNumber: 2
-  }, 'correct error message');
+  }], 'correct error message');
+  t.end();
+});
+
+test('hierarchy - anonymous', function (t) {
+  var result = evaluate(function () {
+    /** Test */
+  })[0];
+
+  t.equal(result.description, 'Test');
+  t.deepEqual(result.errors, [{
+    message: 'could not determine @name for hierarchy'
+  }]);
   t.end();
 });