refactor(nest): Better nesting implementation

This nesting implementation uses a proper recursive tree algorithm

Fixes #554

BREAKING CHANGE: referencing inferred destructure params without
renaming them, like $0.x, from JSDoc comments will no longer
work. To reference them, instead add a param tag to name the
destructuring param, and then refer to members of that name.

Before:

```js
/**
 * @param {number} $0.x a member of x
 */
function a({ x }) {}
```

After:

```js
/**
 * @param {Object} options
 * @param {number} options.x a member of x
 */
function a({ x }) {}
```

Author: tmcw

Diff for: declarations/comment.js

@@ -58,7 +58,21 @@ declare type CommentContextGitHub = {
   url: string
 };
 
-declare type CommentTag = {
+declare type CommentTagBase = {
+  title: string
+};
+
+declare type CommentTag = CommentTagBase & {
+  name?: string,
+  title: string,
+  description?: Object,
+  default?: any,
+  lineNumber?: number,
+  type?: DoctrineType,
+  properties?: Array<CommentTag>
+};
+
+declare type CommentTagNamed = CommentTag & {
   name?: string,
   title: string,
   description?: Object,
@@ -88,18 +102,19 @@ declare type Remark = {
 
 declare type Access = 'private' | 'public' | 'protected';
 declare type Scope = 'instance' | 'static' | 'inner' | 'global';
-declare type Kind = 'class' |
-  'constant' |
-  'event' |
-  'external' |
-  'file' |
-  'function' |
-  'member' |
-  'mixin' |
-  'module' |
-  'namespace' |
-  'typedef' |
-  'interface';
+declare type Kind =
+  | 'class'
+  | 'constant'
+  | 'event'
+  | 'external'
+  | 'file'
+  | 'function'
+  | 'member'
+  | 'mixin'
+  | 'module'
+  | 'namespace'
+  | 'typedef'
+  | 'interface';
 
 declare type Comment = {
   errors: Array<CommentError>,
@@ -152,4 +167,4 @@ declare type ReducedComment = {
   name: string,
   kind: ?Kind,
   scope?: ?Scope
-}
+};

Diff for: default_theme/section._

@@ -52,7 +52,7 @@
             = <code><%- param.default %></code><% } %>)</code>
 	    <%= md(param.description, true) %>
           </div>
-          <% if (param.properties) { %>
+          <% if (param.properties && param.properties.length) { %>
           <table class='mt1 mb2 fixed-table h5 col-12'>
             <colgroup>
               <col width='30%' />
@@ -93,7 +93,7 @@
           <% } %><% if (property.description) {
 	    %>: <%= md(property.description, true) %><%
 	  } %>
-          <% if (property.properties) { %>
+          <% if (property.properties && property.properties.length) { %>
             <ul>
               <% property.properties.forEach(function(property) { %>
                 <li><code><%- property.name %></code> <%= formatType(property.type) %>

Diff for: index.js

@@ -45,13 +45,10 @@ function pipeline() {
   };
 }
 
-
-
-function configure(indexes, args)/*: Promise<InputsConfig> */ {
+function configure(indexes, args) /*: Promise<InputsConfig> */ {
   let mergedConfig = mergeConfig(args);
 
   return mergedConfig.then(config => {
-
     let expandedInputs = expandInputs(indexes, config);
 
     return expandedInputs.then(inputs => {
@@ -71,8 +68,10 @@ function configure(indexes, args)/*: Promise<InputsConfig> */ {
  * @param {Object} config options
  * @returns {Promise<Array<string>>} promise with results
  */
-function expandInputs(indexes/*: string|Array<string> */,
-  config /*: DocumentationConfig */) {
+function expandInputs(
+  indexes /*: string|Array<string> */,
+  config /*: DocumentationConfig */
+) {
   // Ensure that indexes is an array of strings
   indexes = [].concat(indexes);
 
@@ -91,40 +90,42 @@ function buildInternal(inputsAndConfig) {
     config.access = ['public', 'undefined', 'protected'];
   }
 
-  var parseFn = (config.polyglot) ? polyglot : parseJavaScript;
+  var parseFn = config.polyglot ? polyglot : parseJavaScript;
 
   var buildPipeline = pipeline(
     inferName,
     inferAccess(config.inferPrivate),
     inferAugments,
     inferKind,
+    nest,
     inferParams,
     inferProperties,
     inferReturn,
     inferMembership(),
     inferType,
-    nest,
     config.github && github,
-    garbageCollect);
+    garbageCollect
+  );
 
-  let extractedComments = _.flatMap(inputs, function (sourceFile) {
+  let extractedComments = _.flatMap(inputs, function(sourceFile) {
     if (!sourceFile.source) {
       sourceFile.source = fs.readFileSync(sourceFile.file, 'utf8');
     }
 
     return parseFn(sourceFile, config).map(buildPipeline);
   }).filter(Boolean);
 
-  return filterAccess(config.access,
-    hierarchy(
-      sort(extractedComments, config)));
+  return filterAccess(
+    config.access,
+    hierarchy(sort(extractedComments, config))
+  );
 }
 
 function lintInternal(inputsAndConfig) {
   let inputs = inputsAndConfig.inputs;
   let config = inputsAndConfig.config;
 
-  let parseFn = (config.polyglot) ? polyglot : parseJavaScript;
+  let parseFn = config.polyglot ? polyglot : parseJavaScript;
 
   let lintPipeline = pipeline(
     lintComments,
@@ -137,7 +138,8 @@ function lintInternal(inputsAndConfig) {
     inferReturn,
     inferMembership(),
     inferType,
-    nest);
+    nest
+  );
 
   let extractedComments = _.flatMap(inputs, sourceFile => {
     if (!sourceFile.source) {
@@ -183,8 +185,7 @@ function lintInternal(inputsAndConfig) {
  *   }
  * });
  */
-let lint = (indexes, args) => configure(indexes, args)
-  .then(lintInternal);
+let lint = (indexes, args) => configure(indexes, args).then(lintInternal);
 
 /**
  * Generate JavaScript documentation as a list of parsed JSDoc
@@ -227,8 +228,7 @@ let lint = (indexes, args) => configure(indexes, args)
  *   // any other kind of code data.
  * });
  */
-let build = (indexes, args) => configure(indexes, args)
-  .then(buildInternal);
+let build = (indexes, args) => configure(indexes, args).then(buildInternal);
 
 /**
  * Documentation's formats are modular methods that take comments
@@ -240,9 +240,8 @@ let build = (indexes, args) => configure(indexes, args)
 var formats = {
   html: require('./lib/output/html'),
   md: require('./lib/output/markdown'),
-  remark: (comments/*: Array<Comment> */, config/*: DocumentationConfig */) =>
-    markdownAST(comments, config)
-      .then(res => JSON.stringify(res, null, 2)),
+  remark: (comments /*: Array<Comment> */, config /*: DocumentationConfig */) =>
+    markdownAST(comments, config).then(res => JSON.stringify(res, null, 2)),
   json: require('./lib/output/json')
 };