Rearrange and document params

Author: tmcw

Diff for: lib/infer/params.js

@@ -9,14 +9,57 @@ const flowDoctrine = require('../flow_doctrine');
 const util = require('util');
 const debuglog = util.debuglog('infer');
 
-const PATH_SPLIT_CAPTURING = /(\[])?(\.)/g;
+/**
+ * Infers param tags by reading function parameter names
+ *
+ * @param {Object} comment parsed comment
+ * @returns {Object} comment with parameters
+ */
+function inferParams(comment /*: Comment */) {
+  var path = findTarget(comment.context.ast);
+
+  // In case of `/** */ var x = function () {}` findTarget returns
+  // the declarator.
+  if (t.isVariableDeclarator(path)) {
+    path = path.get('init');
+  }
+
+  if (!t.isFunction(path)) {
+    return comment;
+  }
 
+  // Then merge the trees. This is the hard part.
+  return _.assign(comment, {
+    params: mergeTrees(
+      path.node.params.map((param, i) => paramToDoc(param, i, '')),
+      comment.params
+    )
+  });
+}
+
+// Utility methods ============================================================
+//
 function addPrefix(doc /*: CommentTagNamed */, prefix) {
   return _.assign(doc, {
     name: prefix + doc.name
   });
 }
+const PATH_SPLIT_CAPTURING = /(\[])?(\.)/g;
 
+/**
+ * Index tags by their `name` property into an ES6 map.
+ */
+function mapTags(tags) {
+  return new Map(
+    tags.map(tag => {
+      return [tag.name, tag];
+    })
+  );
+}
+
+// ___toDoc methods ============================================================
+//
+// These methods take Babel AST nodes and output equivalent JSDoc parameter tags.
 function destructuringObjectParamToDoc(param, i, prefix) /*: CommentTag */ {
   return {
     title: 'param',
@@ -174,38 +217,19 @@ function paramToDoc(
   }
 }
 
-/**
- * Infers param tags by reading function parameter names
- *
- * @param {Object} comment parsed comment
- * @returns {Object} comment with parameters
- */
-function inferParams(comment /*: Comment */) {
-  var path = findTarget(comment.context.ast);
-
-  // In case of `/** */ var x = function () {}` findTarget returns
-  // the declarator.
-  if (t.isVariableDeclarator(path)) {
-    path = path.get('init');
-  }
-
-  if (!t.isFunction(path)) {
-    return comment;
-  }
-
-  // Then merge the trees. This is the hard part.
-  return _.assign(comment, {
-    params: mergeTrees(
-      path.node.params.map((param, i) => paramToDoc(param, i, '')),
-      comment.params
-    )
-  });
-}
-
 /**
  * Recurse through a potentially nested parameter tag,
  * replacing the auto-generated name, like $0, with an explicit
- * name provided from a JSDoc comment
+ * name provided from a JSDoc comment. For instance, if you have a code
+ * block like
+ *
+ * function f({ x });
+ *
+ * It would by default be documented with a first param $0, with a member $0.x
+ *
+ * If you specify the name of the param, then it could be documented with, say,
+ * options and options.x. So we need to recursively rename not just $0 but
+ * also $0.x and maybe $0.x.y.z all to options.x and options.x.y.z
  */
 function renameTree(node, explicitName) {
   var parts = node.name.split(PATH_SPLIT_CAPTURING);
@@ -216,8 +240,6 @@ function renameTree(node, explicitName) {
   }
 }
 
-var mapTags = tags => new Map(tags.map(tag => [tag.name, tag]));
-
 function mergeTrees(inferred, explicit) {
   // The first order of business is ensuring that the root types are specified
   // in the right order. For the order of arguments, the inferred reality