Full hierarchy support

[jfirebaugh]

This is a pretty big lift:

• Need to implement full namepath parsing
• Everything downstream of hierarchy needs to deal with a new input format: tree rather than array of comments
  • JSON output
  • Markdown output
  • HTML output
  • Theme templates (for events property moving to members.event)
• Update RECIPES

Refs #111.

[tmcw]

Everything downstream of hierarchy needs to deal with a new input format: tree rather than array of comments

In the last Markdown refactor, markdown_ast does nested children same as HTML did. Though they'll both need to handle the new tree structure.

[tmcw]

Do you have a preference for the children: { static: [], instance: [], event: [] } format we have currently? I've wondered about flattening it into children: [ ], since static, instance, and event are implied by the children's properties, and with sorting we may not always have them as exclusive groups

[jfirebaugh]

I think they need to be unflattened -- in order to enable efficient traversal, these are objects keyed by name (not arrays), and you can have a class with a static member and an instance member with the same name, for instance.

[jfirebaugh]

These changes are breaking assumptions in the multisignature test:

/**
 * Get the time
 * @returns {Date} the current date
 */

/**
 * Set the time
 * @param {Date} time the current time
 * @returns {undefined} nothing
 */
function getTheTime(time) {
  if (arguments.length === 0) {
    return new Date();
  } else {
    theTime = time;
  }
}

I'm not really sure this should be supported.

[jfirebaugh]

I'm seeing now that events should not be included in a separate scope category alongside static, instance, and inner. Instead they're given a special event: namespace and used as instance members (though I suppose they could be static as well).

http://usejsdoc.org/tags-event.html

[jfirebaugh]

Okay, after much massaging, I decided that not much has to change after all. The changes now are pleasingly contained:

• Hierarchy output does not change
• Removed special-casing of events scope in 9dcf926 -- we can handle this in themes later
• Punt on full namepath parsing for now -- this means we don't handle things like @memberof Foo#bar.baz~quux yet.

👀 @tmcw

[tmcw]

👍 lgtm