fix: Infer parameters for classes from constructors

docs/RECIPES.md

@@ -1,3 +1,42 @@
+## Classes
+
+ES6 has a nice, formal way of declaring classes. documentation.js handles it well:
+here are tips for dealing with them.
+
+**Document constructor parameters with the class, not the constructor method.**
+
+Do:
+
+```js
+/**
+ * A table object
+ * @param {number} width
+ * @param {number} height
+ */
+class Table {
+  constructor(width, height) {
+    this.width = width;
+    this.height = height;
+  }
+}
+```
+
+Don't:
+
+```js
+/** A table object */
+class Table {
+  /*
+   * @param {number} width
+   * @param {number} height
+   */
+  constructor(width, height) {
+    this.width = width;
+    this.height = height;
+  }
+}
+```
+
 ## Destructuring Parameters
 
 In ES6, you can use [destructuring assignment in functions](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment):

lib/extractors/exported.js

@@ -165,7 +165,11 @@ function traverseExportedSubtree(path, data, addComments, overrideName) {
         path.skip();
       },
       Method(path) {
-        addComments(data, path);
+        // Don't explicitly document constructor methods: their
+        // parameters are output as part of the class itself.
+        if (path.node.kind !== 'constructor') {
+          addComments(data, path);
+        }
         path.skip();
       }
     });

lib/infer/params.js

@@ -7,7 +7,7 @@ const _ = require('lodash');
 const findTarget = require('./finders').findTarget;
 const flowDoctrine = require('../flow_doctrine');
 const util = require('util');
-const debuglog = util.debuglog('infer');
+const debuglog = util.debuglog('documentation');
 
 /**
  * Infers param tags by reading function parameter names
@@ -24,13 +24,27 @@ function inferParams(comment /*: Comment */) {
     path = path.get('init');
   }
 
+  // If this is an ES6 class with a constructor method, infer
+  // parameters from that constructor method.
+  if (t.isClassDeclaration(path)) {
+    let constructor = path.node.body.body.find(item => {
+      // https://github.com/babel/babylon/blob/master/ast/spec.md#classbody
+      return t.isClassMethod(item) && item.kind === 'constructor';
+    });
+    if (constructor) {
+      return inferAndCombineParams(constructor.params, comment);
+    }
+  }
+
   if (!t.isFunction(path)) {
     return comment;
   }
 
-  var inferredParams = path.node.params.map((param, i) =>
-    paramToDoc(param, '', i));
+  return inferAndCombineParams(path.node.params, comment);
+}
 
+function inferAndCombineParams(params, comment) {
+  var inferredParams = params.map((param, i) => paramToDoc(param, '', i));
   var mergedParams = mergeTrees(inferredParams, comment.params);
 
   // Then merge the trees. This is the hard part.

lib/parsers/javascript.js

@@ -2,9 +2,12 @@
 /* @flow */
 
 var _ = require('lodash'),
+  t = require('babel-types'),
   parse = require('../../lib/parse'),
   walkComments = require('../extractors/comments'),
   walkExported = require('../extractors/exported'),
+  util = require('util'),
+  debuglog = util.debuglog('documentation'),
   parseToAst = require('./parse_to_ast');
 
 /**
@@ -89,6 +92,13 @@ function _addComment(
         value: path
       });
 
+      // #689
+      if (t.isClassMethod(path) && path.node.kind === 'constructor') {
+        debuglog(
+          'A constructor was documented explicitly: document along with the class instead'
+        );
+      }
+
       if (path.parentPath && path.parentPath.node) {
         var parentNode = path.parentPath.node;
         context.code = data.source.substring(parentNode.start, parentNode.end);

test/fixture/document-exported.input.js

@@ -1,6 +1,7 @@
 // Options: {"documentExported": true}
 
 export class Class {
+  constructor(a: string) {}
   classMethod() {}
   get classGetter() {}
   set classSetter(v) {}