diff --git a/docs/RECIPES.md b/docs/RECIPES.md index 3403f634b..c747a7749 100644 --- a/docs/RECIPES.md +++ b/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): diff --git a/lib/extractors/exported.js b/lib/extractors/exported.js index c400e49e4..8e00ae917 100644 --- a/lib/extractors/exported.js +++ b/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(); } }); diff --git a/lib/infer/params.js b/lib/infer/params.js index 2861bee70..dd92bad1b 100644 --- a/lib/infer/params.js +++ b/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. diff --git a/lib/parsers/javascript.js b/lib/parsers/javascript.js index 17d4f8121..f584cafc3 100644 --- a/lib/parsers/javascript.js +++ b/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); diff --git a/test/fixture/document-exported.input.js b/test/fixture/document-exported.input.js index 4d4ab6ea0..3c2c1e0dc 100644 --- a/test/fixture/document-exported.input.js +++ b/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) {} diff --git a/test/fixture/document-exported.output.json b/test/fixture/document-exported.output.json index bbe960428..a5fbd453b 100644 --- a/test/fixture/document-exported.output.json +++ b/test/fixture/document-exported.output.json @@ -175,7 +175,7 @@ "column": 0 }, "end": { - "line": 10, + "line": 11, "column": 1 } }, @@ -186,7 +186,7 @@ "column": 0 }, "end": { - "line": 10, + "line": 11, "column": 1 } } @@ -194,7 +194,17 @@ "augments": [], "errors": [], "examples": [], - "params": [], + "params": [ + { + "title": "param", + "name": "a", + "lineNumber": 4, + "type": { + "type": "NameExpression", + "name": "string" + } + } + ], "properties": [], "returns": [], "sees": [], @@ -211,22 +221,22 @@ "tags": [], "loc": { "start": { - "line": 4, + "line": 5, "column": 2 }, "end": { - "line": 4, + "line": 5, "column": 18 } }, "context": { "loc": { "start": { - "line": 4, + "line": 5, "column": 2 }, "end": { - "line": 4, + "line": 5, "column": 18 } } @@ -269,22 +279,22 @@ "tags": [], "loc": { "start": { - "line": 5, + "line": 6, "column": 2 }, "end": { - "line": 5, + "line": 6, "column": 22 } }, "context": { "loc": { "start": { - "line": 5, + "line": 6, "column": 2 }, "end": { - "line": 5, + "line": 6, "column": 22 } } @@ -327,22 +337,22 @@ "tags": [], "loc": { "start": { - "line": 6, + "line": 7, "column": 2 }, "end": { - "line": 6, + "line": 7, "column": 23 } }, "context": { "loc": { "start": { - "line": 6, + "line": 7, "column": 2 }, "end": { - "line": 6, + "line": 7, "column": 23 } } @@ -354,7 +364,7 @@ { "title": "param", "name": "v", - "lineNumber": 6 + "lineNumber": 7 } ], "properties": [], @@ -394,22 +404,22 @@ "tags": [], "loc": { "start": { - "line": 7, + "line": 8, "column": 2 }, "end": { - "line": 7, + "line": 8, "column": 26 } }, "context": { "loc": { "start": { - "line": 7, + "line": 8, "column": 2 }, "end": { - "line": 7, + "line": 8, "column": 26 } } @@ -452,22 +462,22 @@ "tags": [], "loc": { "start": { - "line": 8, + "line": 9, "column": 2 }, "end": { - "line": 8, + "line": 9, "column": 30 } }, "context": { "loc": { "start": { - "line": 8, + "line": 9, "column": 2 }, "end": { - "line": 8, + "line": 9, "column": 30 } } @@ -510,22 +520,22 @@ "tags": [], "loc": { "start": { - "line": 9, + "line": 10, "column": 2 }, "end": { - "line": 9, + "line": 10, "column": 31 } }, "context": { "loc": { "start": { - "line": 9, + "line": 10, "column": 2 }, "end": { - "line": 9, + "line": 10, "column": 31 } } @@ -537,7 +547,7 @@ { "title": "param", "name": "v", - "lineNumber": 9 + "lineNumber": 10 } ], "properties": [], @@ -807,22 +817,22 @@ "tags": [], "loc": { "start": { - "line": 12, + "line": 13, "column": 0 }, "end": { - "line": 18, + "line": 19, "column": 2 } }, "context": { "loc": { "start": { - "line": 12, + "line": 13, "column": 0 }, "end": { - "line": 18, + "line": 19, "column": 2 } } @@ -848,22 +858,22 @@ "tags": [], "loc": { "start": { - "line": 13, + "line": 14, "column": 2 }, "end": { - "line": 13, + "line": 14, "column": 13 } }, "context": { "loc": { "start": { - "line": 13, + "line": 14, "column": 2 }, "end": { - "line": 13, + "line": 14, "column": 13 } } @@ -905,22 +915,22 @@ "tags": [], "loc": { "start": { - "line": 14, + "line": 15, "column": 2 }, "end": { - "line": 14, + "line": 15, "column": 17 } }, "context": { "loc": { "start": { - "line": 14, + "line": 15, "column": 2 }, "end": { - "line": 14, + "line": 15, "column": 17 } } @@ -962,22 +972,22 @@ "tags": [], "loc": { "start": { - "line": 15, + "line": 16, "column": 2 }, "end": { - "line": 15, + "line": 16, "column": 18 } }, "context": { "loc": { "start": { - "line": 15, + "line": 16, "column": 2 }, "end": { - "line": 15, + "line": 16, "column": 18 } } @@ -989,7 +999,7 @@ { "title": "param", "name": "v", - "lineNumber": 15 + "lineNumber": 16 } ], "properties": [], @@ -1025,22 +1035,22 @@ "tags": [], "loc": { "start": { - "line": 16, + "line": 17, "column": 2 }, "end": { - "line": 16, + "line": 17, "column": 10 } }, "context": { "loc": { "start": { - "line": 16, + "line": 17, "column": 2 }, "end": { - "line": 16, + "line": 17, "column": 10 } } @@ -1080,22 +1090,22 @@ "tags": [], "loc": { "start": { - "line": 17, + "line": 18, "column": 2 }, "end": { - "line": 17, + "line": 18, "column": 21 } }, "context": { "loc": { "start": { - "line": 17, + "line": 18, "column": 2 }, "end": { - "line": 17, + "line": 18, "column": 21 } } @@ -1146,22 +1156,22 @@ "tags": [], "loc": { "start": { - "line": 54, + "line": 55, "column": 0 }, "end": { - "line": 54, + "line": 55, "column": 16 } }, "context": { "loc": { "start": { - "line": 54, + "line": 55, "column": 0 }, "end": { - "line": 54, + "line": 55, "column": 16 } } @@ -1197,22 +1207,22 @@ "tags": [], "loc": { "start": { - "line": 55, + "line": 56, "column": 0 }, "end": { - "line": 55, + "line": 56, "column": 16 } }, "context": { "loc": { "start": { - "line": 55, + "line": 56, "column": 0 }, "end": { - "line": 55, + "line": 56, "column": 16 } } @@ -1248,22 +1258,22 @@ "tags": [], "loc": { "start": { - "line": 59, + "line": 60, "column": 0 }, "end": { - "line": 59, + "line": 60, "column": 23 } }, "context": { "loc": { "start": { - "line": 59, + "line": 60, "column": 0 }, "end": { - "line": 59, + "line": 60, "column": 23 } } @@ -1303,22 +1313,22 @@ "tags": [], "loc": { "start": { - "line": 60, + "line": 61, "column": 0 }, "end": { - "line": 60, + "line": 61, "column": 17 } }, "context": { "loc": { "start": { - "line": 60, + "line": 61, "column": 0 }, "end": { - "line": 60, + "line": 61, "column": 17 } } @@ -1358,22 +1368,22 @@ "tags": [], "loc": { "start": { - "line": 61, + "line": 62, "column": 0 }, "end": { - "line": 61, + "line": 62, "column": 17 } }, "context": { "loc": { "start": { - "line": 61, + "line": 62, "column": 0 }, "end": { - "line": 61, + "line": 62, "column": 17 } } @@ -1413,22 +1423,22 @@ "tags": [], "loc": { "start": { - "line": 67, + "line": 68, "column": 0 }, "end": { - "line": 67, + "line": 68, "column": 34 } }, "context": { "loc": { "start": { - "line": 67, + "line": 68, "column": 0 }, "end": { - "line": 67, + "line": 68, "column": 34 } } @@ -1440,7 +1450,7 @@ { "title": "param", "name": "x", - "lineNumber": 67, + "lineNumber": 68, "type": { "type": "NameExpression", "name": "X" @@ -1474,22 +1484,22 @@ "tags": [], "loc": { "start": { - "line": 71, + "line": 72, "column": 0 }, "end": { - "line": 73, + "line": 74, "column": 2 } }, "context": { "loc": { "start": { - "line": 71, + "line": 72, "column": 0 }, "end": { - "line": 73, + "line": 74, "column": 2 } } @@ -1515,22 +1525,22 @@ "tags": [], "loc": { "start": { - "line": 72, + "line": 73, "column": 2 }, "end": { - "line": 72, + "line": 73, "column": 10 } }, "context": { "loc": { "start": { - "line": 72, + "line": 73, "column": 2 }, "end": { - "line": 72, + "line": 73, "column": 10 } } @@ -1632,22 +1642,22 @@ "tags": [], "loc": { "start": { - "line": 75, + "line": 76, "column": 0 }, "end": { - "line": 75, + "line": 76, "column": 17 } }, "context": { "loc": { "start": { - "line": 76, + "line": 77, "column": 0 }, "end": { - "line": 79, + "line": 80, "column": 4 } } @@ -1659,7 +1669,7 @@ { "title": "param", "name": "y", - "lineNumber": 76, + "lineNumber": 77, "type": { "type": "NameExpression", "name": "Y" @@ -1693,22 +1703,22 @@ "tags": [], "loc": { "start": { - "line": 77, + "line": 78, "column": 2 }, "end": { - "line": 79, + "line": 80, "column": 3 } }, "context": { "loc": { "start": { - "line": 77, + "line": 78, "column": 2 }, "end": { - "line": 79, + "line": 80, "column": 3 } } @@ -1734,22 +1744,22 @@ "tags": [], "loc": { "start": { - "line": 78, + "line": 79, "column": 4 }, "end": { - "line": 78, + "line": 79, "column": 12 } }, "context": { "loc": { "start": { - "line": 78, + "line": 79, "column": 4 }, "end": { - "line": 78, + "line": 79, "column": 12 } } diff --git a/test/fixture/document-exported.output.md b/test/fixture/document-exported.output.md index 67a06f971..a75a60be3 100644 --- a/test/fixture/document-exported.output.md +++ b/test/fixture/document-exported.output.md @@ -45,6 +45,10 @@ ## Class +**Parameters** + +- `a` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** + ### classMethod ### classGetter diff --git a/test/fixture/document-exported.output.md.json b/test/fixture/document-exported.output.md.json index c694294c2..f2c9224c7 100644 --- a/test/fixture/document-exported.output.md.json +++ b/test/fixture/document-exported.output.md.json @@ -82,6 +82,59 @@ } ] }, + { + "type": "strong", + "children": [ + { + "type": "text", + "value": "Parameters" + } + ] + }, + { + "ordered": false, + "type": "list", + "children": [ + { + "type": "listItem", + "children": [ + { + "type": "paragraph", + "children": [ + { + "type": "inlineCode", + "value": "a" + }, + { + "type": "text", + "value": " " + }, + { + "type": "strong", + "children": [ + { + "href": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String", + "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String", + "type": "link", + "children": [ + { + "type": "text", + "value": "string" + } + ] + } + ] + }, + { + "type": "text", + "value": " " + } + ] + } + ] + } + ] + }, { "depth": 3, "type": "heading", diff --git a/test/fixture/es6-class.input.js b/test/fixture/es6-class.input.js index 10cf6c7c8..e8e57d12a 100644 --- a/test/fixture/es6-class.input.js +++ b/test/fixture/es6-class.input.js @@ -5,17 +5,21 @@ class Foo extends React.Component {} /** * Does nothing. This is from issue #556 + * @param {string} str */ -export default class Bar { - /** - * Creates a new instance - * @param {string} str - */ +export class Bar { constructor(str) { /** - * A useless property - * @type {string} - */ + * A useless property + * @type {string} + */ this.bar = ''; } } + +/** + * This class has fully inferred constructor parameters. + */ +export class Baz { + constructor(n: number, l: Array) {} +} diff --git a/test/fixture/es6-class.output.json b/test/fixture/es6-class.output.json index 78ce308f3..946da68c4 100644 --- a/test/fixture/es6-class.output.json +++ b/test/fixture/es6-class.output.json @@ -159,25 +159,36 @@ } } }, - "tags": [], + "tags": [ + { + "title": "param", + "description": null, + "lineNumber": 2, + "type": { + "type": "NameExpression", + "name": "string" + }, + "name": "str" + } + ], "loc": { "start": { "line": 6, "column": 0 }, "end": { - "line": 8, + "line": 9, "column": 3 } }, "context": { "loc": { "start": { - "line": 9, + "line": 10, "column": 0 }, "end": { - "line": 21, + "line": 18, "column": 1 } } @@ -185,7 +196,17 @@ "augments": [], "errors": [], "examples": [], - "params": [], + "params": [ + { + "title": "param", + "name": "str", + "lineNumber": 2, + "type": { + "type": "NameExpression", + "name": "string" + } + } + ], "properties": [], "returns": [], "sees": [], @@ -197,136 +218,6 @@ "global": [], "inner": [], "instance": [ - { - "description": { - "type": "root", - "children": [ - { - "type": "paragraph", - "children": [ - { - "type": "text", - "value": "Creates a new instance", - "position": { - "start": { - "line": 1, - "column": 1, - "offset": 0 - }, - "end": { - "line": 1, - "column": 23, - "offset": 22 - }, - "indent": [] - } - } - ], - "position": { - "start": { - "line": 1, - "column": 1, - "offset": 0 - }, - "end": { - "line": 1, - "column": 23, - "offset": 22 - }, - "indent": [] - } - } - ], - "position": { - "start": { - "line": 1, - "column": 1, - "offset": 0 - }, - "end": { - "line": 1, - "column": 23, - "offset": 22 - } - } - }, - "tags": [ - { - "title": "param", - "description": null, - "lineNumber": 2, - "type": { - "type": "NameExpression", - "name": "string" - }, - "name": "str" - } - ], - "loc": { - "start": { - "line": 10, - "column": 2 - }, - "end": { - "line": 13, - "column": 7 - } - }, - "context": { - "loc": { - "start": { - "line": 14, - "column": 2 - }, - "end": { - "line": 20, - "column": 3 - } - } - }, - "augments": [], - "errors": [], - "examples": [], - "params": [ - { - "title": "param", - "name": "str", - "lineNumber": 2, - "type": { - "type": "NameExpression", - "name": "string" - } - } - ], - "properties": [], - "returns": [], - "sees": [], - "throws": [], - "todos": [], - "name": "constructor", - "kind": "function", - "memberof": "Bar", - "scope": "instance", - "members": { - "global": [], - "inner": [], - "instance": [], - "events": [], - "static": [] - }, - "path": [ - { - "name": "Bar", - "kind": "class" - }, - { - "name": "constructor", - "kind": "function", - "scope": "instance" - } - ], - "namespace": "Bar#constructor" - }, { "description": { "type": "root", @@ -393,22 +284,22 @@ ], "loc": { "start": { - "line": 15, + "line": 12, "column": 4 }, "end": { - "line": 18, - "column": 11 + "line": 15, + "column": 7 } }, "context": { "loc": { "start": { - "line": 19, + "line": 16, "column": 4 }, "end": { - "line": 19, + "line": 16, "column": 18 } } @@ -455,5 +346,135 @@ } ], "namespace": "Bar" + }, + { + "description": { + "type": "root", + "children": [ + { + "type": "paragraph", + "children": [ + { + "type": "text", + "value": "This class has fully inferred constructor parameters.", + "position": { + "start": { + "line": 1, + "column": 1, + "offset": 0 + }, + "end": { + "line": 1, + "column": 54, + "offset": 53 + }, + "indent": [] + } + } + ], + "position": { + "start": { + "line": 1, + "column": 1, + "offset": 0 + }, + "end": { + "line": 1, + "column": 54, + "offset": 53 + }, + "indent": [] + } + } + ], + "position": { + "start": { + "line": 1, + "column": 1, + "offset": 0 + }, + "end": { + "line": 1, + "column": 54, + "offset": 53 + } + } + }, + "tags": [], + "loc": { + "start": { + "line": 20, + "column": 0 + }, + "end": { + "line": 22, + "column": 3 + } + }, + "context": { + "loc": { + "start": { + "line": 23, + "column": 0 + }, + "end": { + "line": 25, + "column": 1 + } + } + }, + "augments": [], + "errors": [], + "examples": [], + "params": [ + { + "title": "param", + "name": "n", + "lineNumber": 24, + "type": { + "type": "NameExpression", + "name": "number" + } + }, + { + "title": "param", + "name": "l", + "lineNumber": 24, + "type": { + "type": "TypeApplication", + "expression": { + "type": "NameExpression", + "name": "Array" + }, + "applications": [ + { + "type": "NameExpression", + "name": "string" + } + ] + } + } + ], + "properties": [], + "returns": [], + "sees": [], + "throws": [], + "todos": [], + "name": "Baz", + "kind": "class", + "members": { + "global": [], + "inner": [], + "instance": [], + "events": [], + "static": [] + }, + "path": [ + { + "name": "Baz", + "kind": "class" + } + ], + "namespace": "Baz" } ] \ No newline at end of file diff --git a/test/fixture/es6-class.output.md b/test/fixture/es6-class.output.md index e19e05243..2d128e772 100644 --- a/test/fixture/es6-class.output.md +++ b/test/fixture/es6-class.output.md @@ -4,8 +4,8 @@ - [Foo](#foo) - [Bar](#bar) - - [constructor](#constructor) - [bar](#bar-1) +- [Baz](#baz) ## Foo @@ -17,10 +17,6 @@ This is my component. This is from issue #458 Does nothing. This is from issue #556 -### constructor - -Creates a new instance - **Parameters** - `str` **[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)** @@ -28,3 +24,12 @@ Creates a new instance ### bar A useless property + +## Baz + +This class has fully inferred constructor parameters. + +**Parameters** + +- `n` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** +- `l` **[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array)<[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String)>** diff --git a/test/fixture/es6-class.output.md.json b/test/fixture/es6-class.output.md.json index be9e2c03f..7b9f040a4 100644 --- a/test/fixture/es6-class.output.md.json +++ b/test/fixture/es6-class.output.md.json @@ -113,51 +113,6 @@ "indent": [] } }, - { - "depth": 3, - "type": "heading", - "children": [ - { - "type": "text", - "value": "constructor" - } - ] - }, - { - "type": "paragraph", - "children": [ - { - "type": "text", - "value": "Creates a new instance", - "position": { - "start": { - "line": 1, - "column": 1, - "offset": 0 - }, - "end": { - "line": 1, - "column": 23, - "offset": 22 - }, - "indent": [] - } - } - ], - "position": { - "start": { - "line": 1, - "column": 1, - "offset": 0 - }, - "end": { - "line": 1, - "column": 23, - "offset": 22 - }, - "indent": [] - } - }, { "type": "strong", "children": [ @@ -255,6 +210,161 @@ }, "indent": [] } + }, + { + "depth": 2, + "type": "heading", + "children": [ + { + "type": "text", + "value": "Baz" + } + ] + }, + { + "type": "paragraph", + "children": [ + { + "type": "text", + "value": "This class has fully inferred constructor parameters.", + "position": { + "start": { + "line": 1, + "column": 1, + "offset": 0 + }, + "end": { + "line": 1, + "column": 54, + "offset": 53 + }, + "indent": [] + } + } + ], + "position": { + "start": { + "line": 1, + "column": 1, + "offset": 0 + }, + "end": { + "line": 1, + "column": 54, + "offset": 53 + }, + "indent": [] + } + }, + { + "type": "strong", + "children": [ + { + "type": "text", + "value": "Parameters" + } + ] + }, + { + "ordered": false, + "type": "list", + "children": [ + { + "type": "listItem", + "children": [ + { + "type": "paragraph", + "children": [ + { + "type": "inlineCode", + "value": "n" + }, + { + "type": "text", + "value": " " + }, + { + "type": "strong", + "children": [ + { + "href": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number", + "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number", + "type": "link", + "children": [ + { + "type": "text", + "value": "number" + } + ] + } + ] + }, + { + "type": "text", + "value": " " + } + ] + } + ] + }, + { + "type": "listItem", + "children": [ + { + "type": "paragraph", + "children": [ + { + "type": "inlineCode", + "value": "l" + }, + { + "type": "text", + "value": " " + }, + { + "type": "strong", + "children": [ + { + "href": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array", + "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array", + "type": "link", + "children": [ + { + "type": "text", + "value": "Array" + } + ] + }, + { + "type": "text", + "value": "<" + }, + { + "href": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String", + "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String", + "type": "link", + "children": [ + { + "type": "text", + "value": "string" + } + ] + }, + { + "type": "text", + "value": ">" + } + ] + }, + { + "type": "text", + "value": " " + } + ] + } + ] + } + ] } ] } \ No newline at end of file diff --git a/test/fixture/es6.input.js b/test/fixture/es6.input.js index 8381a946f..ea5f1a6ed 100644 --- a/test/fixture/es6.input.js +++ b/test/fixture/es6.input.js @@ -22,8 +22,15 @@ var multiply = (a, b) => a * b; /** * This is a sink + * @param {number} height the height of the thing + * @param {number} width the width of the thing */ class Sink { + constructor(height, width) { + this.height = height; + this.width = width; + } + /** * This is a property of the sink. */ @@ -50,15 +57,6 @@ class Sink { get aGetter() { return 42; } - - /** - * @param {number} height the height of the thing - * @param {number} width the width of the thing - */ - constructor(height, width) { - this.height = height; - this.width = width; - } } /** diff --git a/test/fixture/es6.output-toc.md b/test/fixture/es6.output-toc.md index 4a058bf09..7f7abc73f 100644 --- a/test/fixture/es6.output-toc.md +++ b/test/fixture/es6.output-toc.md @@ -44,6 +44,11 @@ Returns **[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Refer This is a sink +**Parameters** + +- `height` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** the height of the thing +- `width` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** the width of the thing + ### staticProp This is a property of the sink. @@ -57,13 +62,6 @@ Is it empty This is a getter method: it should be documented as a property. -### constructor - -**Parameters** - -- `height` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** the height of the thing -- `width` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** the width of the thing - ### hello This method says hello diff --git a/test/fixture/es6.output.json b/test/fixture/es6.output.json index c9c1e99d6..52d58f881 100644 --- a/test/fixture/es6.output.json +++ b/test/fixture/es6.output.json @@ -606,25 +606,46 @@ } } }, - "tags": [], + "tags": [ + { + "title": "param", + "description": "the height of the thing", + "lineNumber": 2, + "type": { + "type": "NameExpression", + "name": "number" + }, + "name": "height" + }, + { + "title": "param", + "description": "the width of the thing", + "lineNumber": 3, + "type": { + "type": "NameExpression", + "name": "number" + }, + "name": "width" + } + ], "loc": { "start": { "line": 23, "column": 0 }, "end": { - "line": 25, + "line": 27, "column": 3 } }, "context": { "loc": { "start": { - "line": 26, + "line": 28, "column": 0 }, "end": { - "line": 62, + "line": 60, "column": 1 } } @@ -632,7 +653,130 @@ "augments": [], "errors": [], "examples": [], - "params": [], + "params": [ + { + "title": "param", + "name": "height", + "lineNumber": 2, + "description": { + "type": "root", + "children": [ + { + "type": "paragraph", + "children": [ + { + "type": "text", + "value": "the height of the thing", + "position": { + "start": { + "line": 1, + "column": 1, + "offset": 0 + }, + "end": { + "line": 1, + "column": 24, + "offset": 23 + }, + "indent": [] + } + } + ], + "position": { + "start": { + "line": 1, + "column": 1, + "offset": 0 + }, + "end": { + "line": 1, + "column": 24, + "offset": 23 + }, + "indent": [] + } + } + ], + "position": { + "start": { + "line": 1, + "column": 1, + "offset": 0 + }, + "end": { + "line": 1, + "column": 24, + "offset": 23 + } + } + }, + "type": { + "type": "NameExpression", + "name": "number" + } + }, + { + "title": "param", + "name": "width", + "lineNumber": 3, + "description": { + "type": "root", + "children": [ + { + "type": "paragraph", + "children": [ + { + "type": "text", + "value": "the width of the thing", + "position": { + "start": { + "line": 1, + "column": 1, + "offset": 0 + }, + "end": { + "line": 1, + "column": 23, + "offset": 22 + }, + "indent": [] + } + } + ], + "position": { + "start": { + "line": 1, + "column": 1, + "offset": 0 + }, + "end": { + "line": 1, + "column": 23, + "offset": 22 + }, + "indent": [] + } + } + ], + "position": { + "start": { + "line": 1, + "column": 1, + "offset": 0 + }, + "end": { + "line": 1, + "column": 23, + "offset": 22 + } + } + }, + "type": { + "type": "NameExpression", + "name": "number" + } + } + ], "properties": [], "returns": [], "sees": [], @@ -700,22 +844,22 @@ "tags": [], "loc": { "start": { - "line": 27, + "line": 34, "column": 2 }, "end": { - "line": 29, + "line": 36, "column": 5 } }, "context": { "loc": { "start": { - "line": 30, + "line": 37, "column": 2 }, "end": { - "line": 30, + "line": 37, "column": 18 } } @@ -809,22 +953,22 @@ "tags": [], "loc": { "start": { - "line": 32, + "line": 39, "column": 2 }, "end": { - "line": 34, + "line": 41, "column": 5 } }, "context": { "loc": { "start": { - "line": 35, + "line": 42, "column": 2 }, "end": { - "line": 37, + "line": 44, "column": 3 } } @@ -922,22 +1066,22 @@ "tags": [], "loc": { "start": { - "line": 46, + "line": 53, "column": 2 }, "end": { - "line": 49, + "line": 56, "column": 5 } }, "context": { "loc": { "start": { - "line": 50, + "line": 57, "column": 2 }, "end": { - "line": 52, + "line": 59, "column": 3 } } @@ -974,208 +1118,6 @@ } ], "namespace": "Sink#aGetter" - }, - { - "description": "", - "tags": [ - { - "title": "param", - "description": "the height of the thing", - "lineNumber": 1, - "type": { - "type": "NameExpression", - "name": "number" - }, - "name": "height" - }, - { - "title": "param", - "description": "the width of the thing", - "lineNumber": 2, - "type": { - "type": "NameExpression", - "name": "number" - }, - "name": "width" - } - ], - "loc": { - "start": { - "line": 54, - "column": 2 - }, - "end": { - "line": 57, - "column": 5 - } - }, - "context": { - "loc": { - "start": { - "line": 58, - "column": 2 - }, - "end": { - "line": 61, - "column": 3 - } - } - }, - "augments": [], - "errors": [], - "examples": [], - "params": [ - { - "title": "param", - "name": "height", - "lineNumber": 1, - "description": { - "type": "root", - "children": [ - { - "type": "paragraph", - "children": [ - { - "type": "text", - "value": "the height of the thing", - "position": { - "start": { - "line": 1, - "column": 1, - "offset": 0 - }, - "end": { - "line": 1, - "column": 24, - "offset": 23 - }, - "indent": [] - } - } - ], - "position": { - "start": { - "line": 1, - "column": 1, - "offset": 0 - }, - "end": { - "line": 1, - "column": 24, - "offset": 23 - }, - "indent": [] - } - } - ], - "position": { - "start": { - "line": 1, - "column": 1, - "offset": 0 - }, - "end": { - "line": 1, - "column": 24, - "offset": 23 - } - } - }, - "type": { - "type": "NameExpression", - "name": "number" - } - }, - { - "title": "param", - "name": "width", - "lineNumber": 2, - "description": { - "type": "root", - "children": [ - { - "type": "paragraph", - "children": [ - { - "type": "text", - "value": "the width of the thing", - "position": { - "start": { - "line": 1, - "column": 1, - "offset": 0 - }, - "end": { - "line": 1, - "column": 23, - "offset": 22 - }, - "indent": [] - } - } - ], - "position": { - "start": { - "line": 1, - "column": 1, - "offset": 0 - }, - "end": { - "line": 1, - "column": 23, - "offset": 22 - }, - "indent": [] - } - } - ], - "position": { - "start": { - "line": 1, - "column": 1, - "offset": 0 - }, - "end": { - "line": 1, - "column": 23, - "offset": 22 - } - } - }, - "type": { - "type": "NameExpression", - "name": "number" - } - } - ], - "properties": [], - "returns": [], - "sees": [], - "throws": [], - "todos": [], - "name": "constructor", - "kind": "function", - "memberof": "Sink", - "scope": "instance", - "members": { - "global": [], - "inner": [], - "instance": [], - "events": [], - "static": [] - }, - "path": [ - { - "name": "Sink", - "kind": "class" - }, - { - "name": "constructor", - "kind": "function", - "scope": "instance" - } - ], - "namespace": "Sink#constructor" } ], "events": [], @@ -1236,22 +1178,22 @@ "tags": [], "loc": { "start": { - "line": 39, + "line": 46, "column": 2 }, "end": { - "line": 41, + "line": 48, "column": 5 } }, "context": { "loc": { "start": { - "line": 42, + "line": 49, "column": 2 }, "end": { - "line": 44, + "line": 51, "column": 3 } } @@ -1365,22 +1307,22 @@ ], "loc": { "start": { - "line": 64, + "line": 62, "column": 0 }, "end": { - "line": 68, + "line": 66, "column": 3 } }, "context": { "loc": { "start": { - "line": 69, + "line": 67, "column": 0 }, "end": { - "line": 69, + "line": 67, "column": 25 } } @@ -1625,22 +1567,22 @@ ], "loc": { "start": { - "line": 71, + "line": 69, "column": 0 }, "end": { - "line": 76, + "line": 74, "column": 3 } }, "context": { "loc": { "start": { - "line": 77, + "line": 75, "column": 0 }, "end": { - "line": 77, + "line": 75, "column": 23 } } @@ -1787,22 +1729,22 @@ "tags": [], "loc": { "start": { - "line": 79, + "line": 77, "column": 0 }, "end": { - "line": 81, + "line": 79, "column": 3 } }, "context": { "loc": { "start": { - "line": 82, + "line": 80, "column": 0 }, "end": { - "line": 82, + "line": 80, "column": 43 } } @@ -1814,7 +1756,7 @@ { "title": "param", "name": "someParams", - "lineNumber": 82, + "lineNumber": 80, "type": { "type": "RestType" } @@ -1898,22 +1840,22 @@ "tags": [], "loc": { "start": { - "line": 84, + "line": 82, "column": 0 }, "end": { - "line": 86, + "line": 84, "column": 3 } }, "context": { "loc": { "start": { - "line": 87, + "line": 85, "column": 0 }, "end": { - "line": 94, + "line": 92, "column": 1 } } @@ -1925,7 +1867,7 @@ { "title": "param", "name": "someParams", - "lineNumber": 87, + "lineNumber": 85, "type": { "type": "RestType", "expression": { @@ -2013,22 +1955,22 @@ "tags": [], "loc": { "start": { - "line": 98, + "line": 96, "column": 0 }, "end": { - "line": 100, + "line": 98, "column": 3 } }, "context": { "loc": { "start": { - "line": 101, + "line": 99, "column": 0 }, "end": { - "line": 101, + "line": 99, "column": 23 } } @@ -2125,22 +2067,22 @@ ], "loc": { "start": { - "line": 105, + "line": 103, "column": 0 }, "end": { - "line": 108, + "line": 106, "column": 3 } }, "context": { "loc": { "start": { - "line": 109, + "line": 107, "column": 0 }, "end": { - "line": 109, + "line": 107, "column": 36 } } @@ -2287,22 +2229,22 @@ "tags": [], "loc": { "start": { - "line": 111, + "line": 109, "column": 0 }, "end": { - "line": 113, + "line": 111, "column": 3 } }, "context": { "loc": { "start": { - "line": 114, + "line": 112, "column": 0 }, "end": { - "line": 116, + "line": 114, "column": 1 } } @@ -2314,7 +2256,7 @@ { "title": "param", "name": "foo", - "lineNumber": 114, + "lineNumber": 112, "default": "'bar'", "type": { "type": "OptionalType" @@ -2405,22 +2347,22 @@ ], "loc": { "start": { - "line": 126, + "line": 124, "column": 0 }, "end": { - "line": 129, + "line": 127, "column": 3 } }, "context": { "loc": { "start": { - "line": 130, + "line": 128, "column": 0 }, "end": { - "line": 130, + "line": 128, "column": 26 } } @@ -2514,22 +2456,22 @@ ], "loc": { "start": { - "line": 132, + "line": 130, "column": 0 }, "end": { - "line": 135, + "line": 133, "column": 3 } }, "context": { "loc": { "start": { - "line": 136, + "line": 134, "column": 0 }, "end": { - "line": 136, + "line": 134, "column": 23 } } @@ -2617,22 +2559,22 @@ "tags": [], "loc": { "start": { - "line": 144, + "line": 142, "column": 0 }, "end": { - "line": 146, + "line": 144, "column": 3 } }, "context": { "loc": { "start": { - "line": 147, + "line": 145, "column": 0 }, "end": { - "line": 147, + "line": 145, "column": 42 } } @@ -2717,22 +2659,22 @@ "tags": [], "loc": { "start": { - "line": 149, + "line": 147, "column": 0 }, "end": { - "line": 149, + "line": 147, "column": 32 } }, "context": { "loc": { "start": { - "line": 150, + "line": 148, "column": 0 }, "end": { - "line": 156, + "line": 154, "column": 1 } } @@ -2744,7 +2686,7 @@ { "title": "param", "name": "array1", - "lineNumber": 151, + "lineNumber": 149, "type": { "type": "TypeApplication", "expression": { @@ -2762,7 +2704,7 @@ { "title": "param", "name": "array2", - "lineNumber": 152, + "lineNumber": 150, "type": { "type": "TypeApplication", "expression": { @@ -2780,7 +2722,7 @@ { "title": "param", "name": "compareFunction", - "lineNumber": 153, + "lineNumber": 151, "type": { "type": "OptionalType", "expression": { @@ -2898,22 +2840,22 @@ "tags": [], "loc": { "start": { - "line": 158, + "line": 156, "column": 0 }, "end": { - "line": 158, + "line": 156, "column": 32 } }, "context": { "loc": { "start": { - "line": 159, + "line": 157, "column": 0 }, "end": { - "line": 161, + "line": 159, "column": 1 } } @@ -2925,7 +2867,7 @@ { "title": "param", "name": "a", - "lineNumber": 159, + "lineNumber": 157, "type": { "type": "NameExpression", "name": "atype.property" diff --git a/test/fixture/es6.output.md b/test/fixture/es6.output.md index 8cd7b6b91..09b3af17c 100644 --- a/test/fixture/es6.output.md +++ b/test/fixture/es6.output.md @@ -9,7 +9,6 @@ - [staticProp](#staticprop) - [empty](#empty) - [aGetter](#agetter) - - [constructor](#constructor) - [hello](#hello) - [makeABasket](#makeabasket) - [makeASink](#makeasink) @@ -68,6 +67,11 @@ Returns **[Number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Refer This is a sink +**Parameters** + +- `height` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** the height of the thing +- `width` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** the width of the thing + ### staticProp This is a property of the sink. @@ -81,13 +85,6 @@ Is it empty This is a getter method: it should be documented as a property. -### constructor - -**Parameters** - -- `height` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** the height of the thing -- `width` **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** the width of the thing - ### hello This method says hello diff --git a/test/fixture/es6.output.md.json b/test/fixture/es6.output.md.json index 4cfaddb81..a90a28b30 100644 --- a/test/fixture/es6.output.md.json +++ b/test/fixture/es6.output.md.json @@ -740,155 +740,6 @@ "indent": [] } }, - { - "depth": 3, - "type": "heading", - "children": [ - { - "type": "text", - "value": "staticProp" - } - ] - }, - { - "type": "paragraph", - "children": [ - { - "type": "text", - "value": "This is a property of the sink.", - "position": { - "start": { - "line": 1, - "column": 1, - "offset": 0 - }, - "end": { - "line": 1, - "column": 32, - "offset": 31 - }, - "indent": [] - } - } - ], - "position": { - "start": { - "line": 1, - "column": 1, - "offset": 0 - }, - "end": { - "line": 1, - "column": 32, - "offset": 31 - }, - "indent": [] - } - }, - { - "depth": 3, - "type": "heading", - "children": [ - { - "type": "text", - "value": "empty" - } - ] - }, - { - "type": "paragraph", - "children": [ - { - "type": "text", - "value": "Is it empty", - "position": { - "start": { - "line": 1, - "column": 1, - "offset": 0 - }, - "end": { - "line": 1, - "column": 12, - "offset": 11 - }, - "indent": [] - } - } - ], - "position": { - "start": { - "line": 1, - "column": 1, - "offset": 0 - }, - "end": { - "line": 1, - "column": 12, - "offset": 11 - }, - "indent": [] - } - }, - { - "depth": 3, - "type": "heading", - "children": [ - { - "type": "text", - "value": "aGetter" - } - ] - }, - { - "type": "paragraph", - "children": [ - { - "type": "text", - "value": "This is a getter method: it should be documented\nas a property.", - "position": { - "start": { - "line": 1, - "column": 1, - "offset": 0 - }, - "end": { - "line": 2, - "column": 15, - "offset": 63 - }, - "indent": [ - 1 - ] - } - } - ], - "position": { - "start": { - "line": 1, - "column": 1, - "offset": 0 - }, - "end": { - "line": 2, - "column": 15, - "offset": 63 - }, - "indent": [ - 1 - ] - } - }, - { - "depth": 3, - "type": "heading", - "children": [ - { - "type": "text", - "value": "constructor" - } - ] - }, { "type": "strong", "children": [ @@ -1050,6 +901,145 @@ } ] }, + { + "depth": 3, + "type": "heading", + "children": [ + { + "type": "text", + "value": "staticProp" + } + ] + }, + { + "type": "paragraph", + "children": [ + { + "type": "text", + "value": "This is a property of the sink.", + "position": { + "start": { + "line": 1, + "column": 1, + "offset": 0 + }, + "end": { + "line": 1, + "column": 32, + "offset": 31 + }, + "indent": [] + } + } + ], + "position": { + "start": { + "line": 1, + "column": 1, + "offset": 0 + }, + "end": { + "line": 1, + "column": 32, + "offset": 31 + }, + "indent": [] + } + }, + { + "depth": 3, + "type": "heading", + "children": [ + { + "type": "text", + "value": "empty" + } + ] + }, + { + "type": "paragraph", + "children": [ + { + "type": "text", + "value": "Is it empty", + "position": { + "start": { + "line": 1, + "column": 1, + "offset": 0 + }, + "end": { + "line": 1, + "column": 12, + "offset": 11 + }, + "indent": [] + } + } + ], + "position": { + "start": { + "line": 1, + "column": 1, + "offset": 0 + }, + "end": { + "line": 1, + "column": 12, + "offset": 11 + }, + "indent": [] + } + }, + { + "depth": 3, + "type": "heading", + "children": [ + { + "type": "text", + "value": "aGetter" + } + ] + }, + { + "type": "paragraph", + "children": [ + { + "type": "text", + "value": "This is a getter method: it should be documented\nas a property.", + "position": { + "start": { + "line": 1, + "column": 1, + "offset": 0 + }, + "end": { + "line": 2, + "column": 15, + "offset": 63 + }, + "indent": [ + 1 + ] + } + } + ], + "position": { + "start": { + "line": 1, + "column": 1, + "offset": 0 + }, + "end": { + "line": 2, + "column": 15, + "offset": 63 + }, + "indent": [ + 1 + ] + } + }, { "depth": 3, "type": "heading",