Extract documentation from Component methods

.eslintrc

@@ -11,10 +11,11 @@
   },
   "globals": {
     "ASTNode": true,
+    "FlowTypeDescriptor": true,
     "Handler": true,
     "NodePath": true,
-    "PropTypeDescriptor": true,
     "PropDescriptor": true,
+    "PropTypeDescriptor": true,
     "Resolver": true
   }
 }

flow/recast.js

@@ -35,6 +35,7 @@ declare class NodePath {
   each(f: (p: NodePath) => any): any;
   map<T>(f: (p: NodePath) => T): Array<T>;
   filter(f: (p: NodePath) => bool): Array<NodePath>;
+  push(node: ASTNode): void;
 }
 
 type Recast = {

package.json

@@ -27,6 +27,7 @@
     "async": "^1.4.2",
     "babel-runtime": "~5.8.25",
     "babylon": "~5.8.3",
+    "doctrine": "^1.2.0",
     "node-dir": "^0.1.10",
     "nomnom": "^1.8.1",
     "recast": "^0.10.41"

src/__tests__/main-test.js

@@ -26,6 +26,7 @@ describe('main', () => {
       expect(docs).toEqual({
         displayName: 'ABC',
         description: 'Example component description',
+        methods: [],
         props: {
           foo: {
             type: {

src/handlers/__tests__/componentMethodsHandler-test.js

@@ -0,0 +1,116 @@
+/*
+ *  Copyright (c) 2015, Facebook, Inc.
+ *  All rights reserved.
+ *
+ *  This source code is licensed under the BSD-style license found in the
+ *  LICENSE file in the root directory of this source tree. An additional grant
+ *  of patent rights can be found in the PATENTS file in the same directory.
+ *
+ */
+
+/*global jest, describe, beforeEach, it, expect*/
+
+jest.autoMockOff();
+jest.mock('../../Documentation');
+
+describe('componentMethodsHandler', () => {
+  let documentation;
+  let componentMethodsHandler;
+  let parse;
+
+  beforeEach(() => {
+    ({parse} = require('../../../tests/utils'));
+    documentation = new (require('../../Documentation'));
+    componentMethodsHandler = require('../componentMethodsHandler');
+  });
+
+  function test(definition) {
+    componentMethodsHandler(documentation, definition);
+    expect(documentation.methods).toEqual([{
+      name: 'foo',
+      docblock: 'The foo method',
+      modifiers: [],
+      returns: {
+        type: {name: 'number'},
+      },
+      params: [{
+        name: 'bar',
+        type: {name: 'number'},
+      }],
+    }, {
+      name: 'bar',
+      docblock: 'Static function',
+      modifiers: ['static'],
+      returns: null,
+      params: [],
+    }]);
+  }
+
+  it('extracts the documentation for an ObjectExpression', () => {
+    const src = `
+      ({
+        /**
+         * The foo method
+         */
+        foo(bar: number): number {
+          return bar;
+        },
+        statics: {
+          /**
+           * Static function
+           */
+          bar() {}
+        },
+        state: {
+          foo: 'foo',
+        },
+        componentDidMount() {},
+        render() {
+          return null;
+        },
+      })
+    `;
+
+    test(parse(src).get('body', 0, 'expression'));
+  });
+
+  it('extracts the documentation for a ClassDeclaration', () => {
+    const src = `
+      class Test {
+        /**
+         * The foo method
+         */
+        foo(bar: number): number {
+          return bar;
+        }
+
+        /**
+         * Static function
+         */
+        static bar() {}
+
+        state = {
+          foo: 'foo',
+        };
+
+        componentDidMount() {}
+
+        render() {
+          return null;
+        }
+      }
+    `;
+
+    test(parse(src).get('body', 0));
+  });
+
+  it('should not find methods for stateless components', () => {
+    const src = `
+      (props) => {}
+    `;
+
+    const definition = parse(src).get('body', 0, 'expression');
+    componentMethodsHandler(documentation, definition);
+    expect(documentation.methods).toEqual([]);
+  });
+});

src/handlers/__tests__/componentMethodsJsDocHandler-test.js

@@ -0,0 +1,148 @@
+/*
+ *  Copyright (c) 2015, Facebook, Inc.
+ *  All rights reserved.
+ *
+ *  This source code is licensed under the BSD-style license found in the
+ *  LICENSE file in the root directory of this source tree. An additional grant
+ *  of patent rights can be found in the PATENTS file in the same directory.
+ *
+ */
+
+/*global jest, describe, beforeEach, it, expect*/
+
+jest.autoMockOff();
+
+describe('componentMethodsHandler', () => {
+  let documentation;
+  let componentMethodsJsDocHandler;
+
+  beforeEach(() => {
+    documentation = new (require('../../Documentation'));
+    componentMethodsJsDocHandler = require('../componentMethodsJsDocHandler');
+  });
+
+  it('stays the same when no docblock is present', () => {
+    const methods = [{
+      name: 'foo',
+      docblock: null,
+      modifiers: [],
+      returns: null,
+      params: [{
+        name: 'test',
+        type: null,
+      }],
+    }];
+    documentation.set('methods', methods);
+    componentMethodsJsDocHandler(documentation, null);
+    expect(documentation.get('methods')).toEqual(methods);
+  });
+
+  it('adds js doc types when no flow types', () => {
+    documentation.set('methods', [{
+      name: 'foo',
+      docblock: `
+        @param {string} test
+        @returns {string}
+      `,
+      modifiers: [],
+      returns: null,
+      params: [{
+        name: 'test',
+        type: null,
+      }],
+    }]);
+    componentMethodsJsDocHandler(documentation, null);
+    expect(documentation.get('methods')).toEqual([{
+      name: 'foo',
+      description: null,
+      docblock: `
+        @param {string} test
+        @returns {string}
+      `,
+      modifiers: [],
+      returns: {
+        type: {name: 'string'},
+        description: null,
+      },
+      params: [{
+        name: 'test',
+        description: null,
+        type: {name: 'string'},
+      }],
+    }]);
+  });
+
+  it('keeps flow types over js doc types', () => {
+    documentation.set('methods', [{
+      name: 'foo',
+      docblock: `
+        @param {string} test
+        @returns {string}
+      `,
+      modifiers: [],
+      returns: {
+        type: {name: 'number'},
+      },
+      params: [{
+        name: 'test',
+        type: {name: 'number'},
+      }],
+    }]);
+    componentMethodsJsDocHandler(documentation, null);
+    expect(documentation.get('methods')).toEqual([{
+      name: 'foo',
+      description: null,
+      docblock: `
+        @param {string} test
+        @returns {string}
+      `,
+      modifiers: [],
+      returns: {
+        type: {name: 'number'},
+        description: null,
+      },
+      params: [{
+        name: 'test',
+        description: null,
+        type: {name: 'number'},
+      }],
+    }]);
+  });
+
+  it('adds descriptions', () => {
+    documentation.set('methods', [{
+      name: 'foo',
+      docblock: `
+        The foo method.
+        @param test The test
+        @returns The number
+      `,
+      modifiers: [],
+      returns: null,
+      params: [{
+        name: 'test',
+        type: null,
+      }],
+    }]);
+    componentMethodsJsDocHandler(documentation, null);
+    expect(documentation.get('methods')).toEqual([{
+      name: 'foo',
+      description: 'The foo method.',
+      docblock: `
+        The foo method.
+        @param test The test
+        @returns The number
+      `,
+      modifiers: [],
+      returns: {
+        description: 'The number',
+        type: null,
+      },
+      params: [{
+        name: 'test',
+        description: 'The test',
+        type: null,
+      }],
+    }]);
+  });
+});

src/handlers/componentMethodsHandler.js

@@ -0,0 +1,73 @@
+/*
+ * Copyright (c) 2015, Facebook, Inc.
+ * All rights reserved.
+ *
+ * This source code is licensed under the BSD-style license found in the
+ * LICENSE file in the root directory of this source tree. An additional grant
+ * of patent rights can be found in the PATENTS file in the same directory.
+ *
+ * @flow
+ */
+
+import recast from 'recast';
+
+import getMemberValuePath from '../utils/getMemberValuePath';
+import getMethodDocumentation from '../utils/getMethodDocumentation';
+import isReactComponentClass from '../utils/isReactComponentClass';
+import isReactComponentMethod from '../utils/isReactComponentMethod';
+import isReactCreateClassCall from '../utils/isReactCreateClassCall';
+
+import type Documentation from '../Documentation';
+
+const {types: {namedTypes: types}} = recast;
+
+function getMethodsDoc(methodPaths) {
+  const methods = [];
+
+  methodPaths.forEach((methodPath) => {
+    if (isReactComponentMethod(methodPath)) {
+      return;
+    }
+
+    methods.push(getMethodDocumentation(methodPath));
+  });
+
+  return methods;
+}
+
+function isFunctionExpression(path) {
+  return types.FunctionExpression.check(path.get('value').node)
+}
+
+/**
+ * Extract all flow types for the methods of a react component. Doesn't
+ * return any react specific lifecycle methods.
+ */
+export default function componentMethodsHandler(
+  documentation: Documentation,
+  path: NodePath
+) {
+  // Extract all methods from the class or object.
+  let methodPaths = [];
+  if (isReactComponentClass(path)) {
+    methodPaths = path
+      .get('body', 'body')
+      .filter(p => types.MethodDefinition.check(p.node) && p.node.kind !== 'constructor');
+  } else if (types.ObjectExpression.check(path.node)) {
+    methodPaths = path.get('properties').filter(isFunctionExpression);
+
+    // Add the statics object properties.
+    const statics = getMemberValuePath(path, 'statics');
+    if (statics) {
+      statics.get('properties').each(p => {
+        if (isFunctionExpression(p)) {
+          p.node.static = true;
+          methodPaths.push(p);
+        }
+      });
+    }
+  }
+
+  const methods = getMethodsDoc(methodPaths);
+  documentation.set('methods', methods);
+}