Infer Flow type aliases into typedefs. Fixes #227

Given the `type` tag introduced with Flow, this can infer
a typedef statement, as well as infer its potentially
nested properties and their types.

This also includes

* Refactor of Markdown AST generation that fixes #228
* Refactor of nest.js to handle multi-level nesting

Author: tmcw

index.js

@@ -13,6 +13,7 @@ var sort = require('./lib/sort'),
   inferName = require('./lib/infer/name'),
   inferKind = require('./lib/infer/kind'),
   inferParams = require('./lib/infer/params'),
+  inferProperties = require('./lib/infer/properties'),
   inferMembership = require('./lib/infer/membership'),
   inferReturn = require('./lib/infer/return'),
   lint = require('./lib/lint');
@@ -96,6 +97,7 @@ module.exports = function (indexes, options, callback) {
                 inferName(),
                 inferKind(),
                 inferParams(),
+                inferProperties(),
                 inferReturn(),
                 inferMembership(),
                 nest,

lib/flow_doctrine.js

@@ -1,6 +1,7 @@
 var namedTypes = {
   'NumberTypeAnnotation': 'number',
   'BooleanTypeAnnotation': 'boolean',
+  'ObjectTypeAnnotation': 'Object',
   'StringTypeAnnotation': 'string'
 };
 

lib/infer/kind.js

@@ -41,7 +41,10 @@ module.exports = function () {
           this.abort();
         }
       },
-
+      visitTypeAlias: function () {
+        comment.kind = 'typedef';
+        this.abort();
+      },
       visitVariableDeclaration: function (path) {
         if (path.value.kind === 'const') {
           comment.kind = 'constant';

lib/infer/properties.js

@@ -0,0 +1,69 @@
+'use strict';
+
+var types = require('ast-types'),
+  flowDoctrine = require('../flow_doctrine');
+
+
+/**
+ * Infers param tags by reading function parameter names
+ *
+ * @name inferParams
+ * @param {Object} comment parsed comment
+ * @returns {Object} comment with parameters
+ */
+module.exports = function () {
+
+  function prefixedName(name, prefix) {
+    if (prefix.length) {
+      return prefix.join('.') + '.' + name;
+    }
+    return name;
+  }
+
+  function propertyToDoc(property, prefix) {
+    var newProperty = {
+      title: 'property',
+      name: prefixedName(property.key.name, prefix),
+      lineNumber: property.loc.start.line,
+      type: flowDoctrine(property.value)
+    };
+    return newProperty;
+  }
+
+  return function inferProperties(comment) {
+
+
+    // Ensure that explicitly specified properties are not overridden
+    // by inferred properties
+    var explicitProperties = (comment.properties || []).reduce(function (memo, property) {
+      memo[property.name] = true;
+      return memo;
+    }, {});
+
+    function inferProperties(value, prefix) {
+      if (value.type === 'ObjectTypeAnnotation') {
+        value.properties.forEach(function (property) {
+          if (explicitProperties[prefixedName(property.key.name, prefix)] === undefined) {
+            if (!comment.properties) {
+              comment.properties = [];
+            }
+            comment.properties = comment.properties.concat(propertyToDoc(property, prefix));
+            // Nested type parameters
+            if (property.value.type === 'ObjectTypeAnnotation') {
+              inferProperties(property.value, prefix.concat(property.key.name));
+            }
+          }
+        });
+      }
+    }
+
+    types.visit(comment.context.ast, {
+      visitTypeAlias: function (path) {
+        inferProperties(path.value.right, []);
+        this.abort();
+      }
+    });
+
+    return comment;
+  };
+};

lib/nest.js

@@ -10,9 +10,12 @@ function nestTag(comment, tagName, target) {
 
   comment[target].forEach(function (tag) {
     index[tag.name] = tag;
-    var parts = tag.name.split(/(\[\])?\./);
+    var parts = tag.name.split(/(\[\])?\./)
+      .filter(function (part) {
+        return part && part !== '[]';
+      });
     if (parts.length > 1) {
-      var parent = index[parts[0]];
+      var parent = index[parts.slice(0, -1).join('.')];
       if (parent === undefined) {
         comment.errors.push({
           message: '@' + tagName + ' ' + tag.name + '\'s parent ' + parts[0] + ' not found',

lib/output/markdown_ast.js

@@ -31,16 +31,17 @@ function commentsToAST(comments, opts, callback) {
             u('inlineCode', param.name),
             u('text', ' '),
             !!param.type && u('strong', [u('text', formatType(param.type))]),
-            u('text', ' '),
-            mdast.parse(formatInlineTags(param.description)),
+            u('text', ' ')
+          ].concat(mdast.parse(formatInlineTags(param.description)).children)
+          .concat([
             !!param.default && u('paragraph', [
               u('text', ' (optional, default '),
               u('inlineCode', param.default),
               u('text', ')')
-            ]),
-            param.properties && paramList(param.properties)
-          ].filter(Boolean))
-        ]);
+            ])
+          ]).filter(Boolean))
+        ].concat(param.properties && paramList(param.properties))
+        .filter(Boolean));
       }));
     }
 
@@ -65,10 +66,11 @@ function commentsToAST(comments, opts, callback) {
             u('paragraph', [
               u('inlineCode', property.name),
               u('text', ' '),
-              u('text', [u('text', formatType(property.type))]),
-              u('text', ' '),
-              mdast.parse(formatInlineTags(property.description))
-            ]),
+              u('strong', [u('text', formatType(property.type))]),
+              u('text', ' ')
+            ]
+            .concat(mdast.parse(formatInlineTags(property.description)).children)
+            .filter(Boolean)),
             property.properties && propertyList(property.properties)
           ].filter(Boolean))
         }));
@@ -86,14 +88,13 @@ function commentsToAST(comments, opts, callback) {
         return u('paragraph', [
           u('text', 'Returns '),
           u('strong', [u('text', formatType(returns.type))]),
-          u('text', ' '),
-          mdast.parse(formatInlineTags(returns.description))
-        ]);
+          u('text', ' ')
+        ].concat(mdast.parse(formatInlineTags(returns.description)).children))
       });
     }
 
     return [u('heading', { depth: depth }, [u('text', comment.name)])]
-    .concat(mdast.parse(formatInlineTags(comment.description)).children[0])
+    .concat(mdast.parse(formatInlineTags(comment.description)).children)
     .concat(paramSection(comment))
     .concat(propertySection(comment))
     .concat(examplesSection(comment))

test/fixture/class.output.custom.md

@@ -4,8 +4,7 @@ This is my class, a demo thing.
 
 **Properties**
 
--   `howMany`  how many things it contains
-
+-   `howMany` **number** how many things it contains
 
 ## getFoo
 
@@ -15,13 +14,10 @@ Get the number 42
 
 -   `getIt` **boolean** whether to get the number
 
-
 Returns **number** forty-two
 
-
 ## getUndefined
 
 Get undefined
 
 Returns **undefined** does not return anything.
-

test/fixture/class.output.md

@@ -4,8 +4,7 @@ This is my class, a demo thing.
 
 **Properties**
 
--   `howMany`  how many things it contains
-
+-   `howMany` **number** how many things it contains
 
 ## getFoo
 
@@ -15,13 +14,10 @@ Get the number 42
 
 -   `getIt` **boolean** whether to get the number
 
-
 Returns **number** forty-two
 
-
 ## getUndefined
 
 Get undefined
 
 Returns **undefined** does not return anything.
-

test/fixture/class.output.md.json

@@ -70,7 +70,7 @@
                   "value": " "
                 },
                 {
-                  "type": "text",
+                  "type": "strong",
                   "children": [
                     {
                       "type": "text",
@@ -83,27 +83,11 @@
                   "value": " "
                 },
                 {
-                  "type": "root",
+                  "type": "paragraph",
                   "children": [
                     {
-                      "type": "paragraph",
-                      "children": [
-                        {
-                          "type": "text",
-                          "value": "how many things it contains",
-                          "position": {
-                            "start": {
-                              "line": 1,
-                              "column": 1
-                            },
-                            "end": {
-                              "line": 1,
-                              "column": 28
-                            },
-                            "indent": []
-                          }
-                        }
-                      ],
+                      "type": "text",
+                      "value": "how many things it contains",
                       "position": {
                         "start": {
                           "line": 1,
@@ -125,7 +109,8 @@
                     "end": {
                       "line": 1,
                       "column": 28
-                    }
+                    },
+                    "indent": []
                   }
                 }
               ]
@@ -216,27 +201,11 @@
                   "value": " "
                 },
                 {
-                  "type": "root",
+                  "type": "paragraph",
                   "children": [
                     {
-                      "type": "paragraph",
-                      "children": [
-                        {
-                          "type": "text",
-                          "value": "whether to get the number",
-                          "position": {
-                            "start": {
-                              "line": 1,
-                              "column": 1
-                            },
-                            "end": {
-                              "line": 1,
-                              "column": 26
-                            },
-                            "indent": []
-                          }
-                        }
-                      ],
+                      "type": "text",
+                      "value": "whether to get the number",
                       "position": {
                         "start": {
                           "line": 1,
@@ -258,7 +227,8 @@
                     "end": {
                       "line": 1,
                       "column": 26
-                    }
+                    },
+                    "indent": []
                   }
                 }
               ]
@@ -288,27 +258,11 @@
           "value": " "
         },
         {
-          "type": "root",
+          "type": "paragraph",
           "children": [
             {
-              "type": "paragraph",
-              "children": [
-                {
-                  "type": "text",
-                  "value": "forty-two",
-                  "position": {
-                    "start": {
-                      "line": 1,
-                      "column": 1
-                    },
-                    "end": {
-                      "line": 1,
-                      "column": 10
-                    },
-                    "indent": []
-                  }
-                }
-              ],
+              "type": "text",
+              "value": "forty-two",
               "position": {
                 "start": {
                   "line": 1,
@@ -330,7 +284,8 @@
             "end": {
               "line": 1,
               "column": 10
-            }
+            },
+            "indent": []
           }
         }
       ]
@@ -397,27 +352,11 @@
           "value": " "
         },
         {
-          "type": "root",
+          "type": "paragraph",
           "children": [
             {
-              "type": "paragraph",
-              "children": [
-                {
-                  "type": "text",
-                  "value": "does not return anything.",
-                  "position": {
-                    "start": {
-                      "line": 1,
-                      "column": 1
-                    },
-                    "end": {
-                      "line": 1,
-                      "column": 26
-                    },
-                    "indent": []
-                  }
-                }
-              ],
+              "type": "text",
+              "value": "does not return anything.",
               "position": {
                 "start": {
                   "line": 1,
@@ -439,7 +378,8 @@
             "end": {
               "line": 1,
               "column": 26
-            }
+            },
+            "indent": []
           }
         }
       ]