Merge pull request #157 from documentationjs/infer-params

Infer parameters. Fixes #51

Author: tmcw

index.js

@@ -13,6 +13,7 @@ var sort = require('./lib/sort'),
   hierarchy = require('./lib/hierarchy'),
   inferName = require('./lib/infer/name'),
   inferKind = require('./lib/infer/kind'),
+  inferParams = require('./lib/infer/params'),
   inferMembership = require('./lib/infer/membership'),
   lint = require('./lib/lint');
 
@@ -59,7 +60,12 @@ module.exports = function (indexes, options, callback) {
         }, [])
         .map(function (comment) {
           // compose nesting & membership to avoid intermediate arrays
-          comment = nestParams(inferMembership(inferKind(inferName(lint(comment)))));
+          comment = nestParams(
+            inferMembership(
+              inferParams(
+                inferKind(
+                  inferName(
+                    lint(comment))))));
           if (options.github) {
             comment = github(comment);
           }

lib/html_helpers.js

@@ -88,6 +88,9 @@ function autolink(paths, text) {
  * // generates String
  */
 function formatType(type, paths) {
+  if (!type) {
+    return '';
+  }
   function recurse(element) {
     return formatType(element, paths);
   }

lib/infer/params.js

@@ -0,0 +1,54 @@
+'use strict';
+
+var types = require('ast-types');
+
+/**
+ * Infers param tags by reading function parameter names
+ *
+ * @name inferParams
+ * @param {Object} comment parsed comment
+ * @returns {Object} comment with parameters
+ */
+module.exports = function inferParams(comment) {
+
+  types.visit(comment.context.ast, {
+    visitFunction: function (path) {
+
+      // Ensure that explicitly specified parameters are not overridden
+      // by inferred parameters
+      var existingParams = (comment.params || []).reduce(function (memo, param) {
+        memo[param.name] = param;
+        return memo;
+      }, {});
+
+      var paramOrder = [];
+
+      path.value.params.forEach(function (param) {
+        if (existingParams[param.name] === undefined) {
+          if (!comment.params) {
+            comment.params = [];
+          }
+          comment.params.push({
+            title: 'param',
+            name: param.name,
+            lineNumber: param.loc.start.line
+          });
+        }
+        paramOrder.push(param.name);
+      });
+
+      // Ensure that if params are specified partially or in
+      // the wrong order, they'll be output in the order
+      // they actually appear in code
+      if (comment.params) {
+        comment.params.sort(function (a, b) {
+          return paramOrder.indexOf(a.name) - paramOrder.indexOf(b.name);
+        });
+      }
+
+      this.abort();
+    }
+  });
+
+  return comment;
+};

test/fixture/es6.output.custom.md

@@ -3,6 +3,14 @@
 This function returns the number one.
 
 
+**Parameters**
+
+-   `a`  
+
+-   `b`  
+
+
+
 Returns **Number** numberone
 
 

test/fixture/es6.output.json

@@ -49,6 +49,18 @@
     ],
     "name": "multiply",
     "kind": "function",
+    "params": [
+      {
+        "title": "param",
+        "name": "a",
+        "lineNumber": 5
+      },
+      {
+        "title": "param",
+        "name": "b",
+        "lineNumber": 5
+      }
+    ],
     "members": {
       "instance": [],
       "static": []

test/fixture/es6.output.md

@@ -3,6 +3,14 @@
 This function returns the number one.
 
 
+**Parameters**
+
+-   `a`  
+
+-   `b`  
+
+
+
 Returns **Number** numberone
 
 

test/fixture/es6.output.md.json

@@ -60,6 +60,98 @@
             }
           }
         },
+        {
+          "type": "root",
+          "children": [
+            {
+              "type": "strong",
+              "children": [
+                {
+                  "type": "text",
+                  "value": "Parameters"
+                }
+              ]
+            },
+            {
+              "ordered": false,
+              "type": "list",
+              "children": [
+                {
+                  "type": "listItem",
+                  "children": [
+                    {
+                      "type": "paragraph",
+                      "children": [
+                        {
+                          "type": "inlineCode",
+                          "value": "a"
+                        },
+                        {
+                          "type": "text",
+                          "value": " "
+                        },
+                        {
+                          "type": "text",
+                          "value": " "
+                        },
+                        {
+                          "type": "root",
+                          "children": [],
+                          "position": {
+                            "start": {
+                              "line": 1,
+                              "column": 1
+                            },
+                            "end": {
+                              "line": 1,
+                              "column": 1
+                            }
+                          }
+                        }
+                      ]
+                    }
+                  ]
+                },
+                {
+                  "type": "listItem",
+                  "children": [
+                    {
+                      "type": "paragraph",
+                      "children": [
+                        {
+                          "type": "inlineCode",
+                          "value": "b"
+                        },
+                        {
+                          "type": "text",
+                          "value": " "
+                        },
+                        {
+                          "type": "text",
+                          "value": " "
+                        },
+                        {
+                          "type": "root",
+                          "children": [],
+                          "position": {
+                            "start": {
+                              "line": 1,
+                              "column": 1
+                            },
+                            "end": {
+                              "line": 1,
+                              "column": 1
+                            }
+                          }
+                        }
+                      ]
+                    }
+                  ]
+                }
+              ]
+            }
+          ]
+        },
         {
           "type": "root",
           "children": [

test/fixture/factory.output.custom.md

@@ -13,9 +13,21 @@ Returns **area** chart
 
 
 
+**Parameters**
+
+-   `selection`  
+
+
+
 
 # data
 
 Sets the chart data.
 
 
+**Parameters**
+
+-   `_`  
+
+
+

test/fixture/factory.output.json

@@ -98,6 +98,13 @@
     },
     "name": "area",
     "kind": "class",
+    "params": [
+      {
+        "title": "param",
+        "name": "selection",
+        "lineNumber": 10
+      }
+    ],
     "members": {
       "instance": [],
       "static": []
@@ -146,6 +153,13 @@
     "function": null,
     "name": "data",
     "kind": "function",
+    "params": [
+      {
+        "title": "param",
+        "name": "_",
+        "lineNumber": 17
+      }
+    ],
     "memberof": "chart",
     "scope": "static",
     "members": {

test/fixture/factory.output.md

@@ -13,9 +13,21 @@ Returns **area** chart
 
 
 
+**Parameters**
+
+-   `selection`  
+
+
+
 
 # data
 
 Sets the chart data.
 
 
+**Parameters**
+
+-   `_`  
+
+
+