Extract documentation from Component methods

This adds documentation for methods of react components. It works with both React.createClass and classes. It reads from jsdoc blocks for descriptions and flow types for type information.

It supports:

- name
- description
- docblock (the raw docblock for further parsing)
- parameters (name, type, description)
- modifiers ('static', 'generator', 'async')
- return (type, description)

It only removes react component methods and leaves removing private methods to the users if they choose so.

Tested on the react-native codebase.

Closes #17

Author: janicduplessis

.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);
+}