Implement flow type inference

cc @thejameskyle

`lib/flow_doctrine.js` is where we convert Babel-parsed
Flow annotations into doctrine-style objects so they
can be formatted with all of the existing helpers.

Author: tmcw

lib/flow_doctrine.js

@@ -0,0 +1,60 @@
+var namedTypes = {
+  'NumberTypeAnnotation': 'number',
+  'BooleanTypeAnnotation': 'boolean',
+  'StringTypeAnnotation': 'string'
+};
+
+var oneToOne = {
+  'AnyTypeAnnotation': {
+    type: 'AllLiteral'
+  }
+};
+
+function flowDoctrine(type) {
+
+  if (type.type in namedTypes) {
+    return {
+      type: 'NameExpression',
+      name: namedTypes[type.type]
+    };
+  }
+
+  if (type.type in oneToOne) {
+    return oneToOne[type.type];
+  }
+
+  if (type.type === 'NullableTypeAnnotation') {
+    return {
+      type: 'OptionalType',
+      expression: flowDoctrine(type.typeAnnotation)
+    };
+  }
+
+  if (type.type === 'UnionTypeAnnotation') {
+    return {
+      type: 'UnionType',
+      elements: type.types.map(flowDoctrine)
+    };
+  }
+
+  if (type.type === 'GenericTypeAnnotation') {
+
+    if (type.typeParameters) {
+      return {
+        type: 'TypeApplication',
+        expression: {
+          type: 'NameExpression',
+          name: type.id.name
+        },
+        applications: type.typeParameters.params.map(flowDoctrine)
+      };
+    }
+
+    return {
+      type: 'NameExpression',
+      name: type.id.name
+    };
+  }
+}
+
+module.exports = flowDoctrine;

lib/infer/params.js

@@ -1,6 +1,7 @@
 'use strict';
 
-var types = require('ast-types');
+var types = require('ast-types'),
+  flowDoctrine = require('../flow_doctrine');
 
 /**
  * Infers param tags by reading function parameter names
@@ -29,11 +30,15 @@ module.exports = function inferParams(comment) {
           if (!comment.params) {
             comment.params = [];
           }
-          comment.params.push({
+          var newParam = {
             title: 'param',
             name: param.name,
             lineNumber: param.loc.start.line
-          });
+          };
+          if (param.typeAnnotation && param.typeAnnotation.typeAnnotation) {
+            newParam.type = flowDoctrine(param.typeAnnotation.typeAnnotation);
+          }
+          comment.params.push(newParam);
         }
         paramOrder[param.name] = i++;
       });

test/fixture/flow-types.input.js

@@ -0,0 +1,10 @@
+/* eslint-disable */
+
+/**
+ * This function returns the number one.
+ */
+function addThem(a: number, b: string, c: ?boolean, d: Array<number>, e: Object, f: Named) {
+  return a + b + c + d + e;
+};
+
+/* eslint-enable */

test/fixture/flow-types.output.custom.md

@@ -0,0 +1,21 @@
+# addThem
+
+This function returns the number one.
+
+
+**Parameters**
+
+-   `a` **number** 
+
+-   `b` **string** 
+
+-   `c` **[boolean]** 
+
+-   `d` **Array<number>** 
+
+-   `e` **Object** 
+
+-   `f` **Named** 
+
+
+

test/fixture/flow-types.output.json

@@ -0,0 +1,108 @@
+[
+  {
+    "description": "This function returns the number one.",
+    "tags": [],
+    "loc": {
+      "start": {
+        "line": 3,
+        "column": 0
+      },
+      "end": {
+        "line": 5,
+        "column": 3
+      }
+    },
+    "context": {
+      "loc": {
+        "start": {
+          "line": 6,
+          "column": 0
+        },
+        "end": {
+          "line": 8,
+          "column": 1
+        }
+      },
+      "code": "/* eslint-disable */\n\n/**\n * This function returns the number one.\n */\nfunction addThem(a: number, b: string, c: ?boolean, d: Array<number>, e: Object, f: Named) {\n  return a + b + c + d + e;\n};\n\n/* eslint-enable */\n"
+    },
+    "errors": [],
+    "name": "addThem",
+    "kind": "function",
+    "params": [
+      {
+        "title": "param",
+        "name": "a",
+        "lineNumber": 6,
+        "type": {
+          "type": "NameExpression",
+          "name": "number"
+        }
+      },
+      {
+        "title": "param",
+        "name": "b",
+        "lineNumber": 6,
+        "type": {
+          "type": "NameExpression",
+          "name": "string"
+        }
+      },
+      {
+        "title": "param",
+        "name": "c",
+        "lineNumber": 6,
+        "type": {
+          "type": "OptionalType",
+          "expression": {
+            "type": "NameExpression",
+            "name": "boolean"
+          }
+        }
+      },
+      {
+        "title": "param",
+        "name": "d",
+        "lineNumber": 6,
+        "type": {
+          "type": "TypeApplication",
+          "expression": {
+            "type": "NameExpression",
+            "name": "Array"
+          },
+          "applications": [
+            {
+              "type": "NameExpression",
+              "name": "number"
+            }
+          ]
+        }
+      },
+      {
+        "title": "param",
+        "name": "e",
+        "lineNumber": 6,
+        "type": {
+          "type": "NameExpression",
+          "name": "Object"
+        }
+      },
+      {
+        "title": "param",
+        "name": "f",
+        "lineNumber": 6,
+        "type": {
+          "type": "NameExpression",
+          "name": "Named"
+        }
+      }
+    ],
+    "members": {
+      "instance": [],
+      "static": []
+    },
+    "events": [],
+    "path": [
+      "addThem"
+    ]
+  }
+]

test/fixture/flow-types.output.md

@@ -0,0 +1,21 @@
+# addThem
+
+This function returns the number one.
+
+
+**Parameters**
+
+-   `a` **number** 
+
+-   `b` **string** 
+
+-   `c` **[boolean]** 
+
+-   `d` **Array<number>** 
+
+-   `e` **Object** 
+
+-   `f` **Named** 
+
+
+