From 7ea89baf90fc27ae5fe7178d1394902ff963c98f Mon Sep 17 00:00:00 2001 From: Erik Arvidsson Date: Wed, 19 Oct 2016 12:44:44 -0700 Subject: [PATCH 1/2] Pick up comments on VariableDeclarations When we find the binding for an export we get the VariableDeclarator. It is common for people to write their JSDoc comment on the parent VariableDeclaration so we check that in case there is no comment on the declarator. Fixes #570 --- lib/extractors/exported.js | 18 +- test/fixture/document-exported.input.js | 10 +- test/fixture/document-exported.output.json | 175 ++++++++++++------ test/fixture/document-exported.output.md | 10 +- test/fixture/document-exported.output.md.json | 75 ++++++-- 5 files changed, 193 insertions(+), 95 deletions(-) diff --git a/lib/extractors/exported.js b/lib/extractors/exported.js index b6b297caa..acc76dfc2 100644 --- a/lib/extractors/exported.js +++ b/lib/extractors/exported.js @@ -27,11 +27,21 @@ function walkExported(ast, data, addComment) { } function getComments(data, path) { - if (!hasJSDocComment(path)) { + var comments = (path.node.leadingComments || []).filter(isJSDocComment); + + if (!comments.length) { + // If this is the first declarator we check for comments on the VariableDeclaration. + if (t.isVariableDeclarator(path) && path.parentPath.get('declarations')[0] === path) { + return getComments(data, path.parentPath); + } + } + + if (!comments.length) { var added = addBlankComment(data, path, path.node); return added ? [added] : []; } - return path.node.leadingComments.filter(isJSDocComment).map(function (comment) { + + return comments.map(function (comment) { return addComment(data, comment.value, comment.loc, path, path.node.loc, true); }).filter(Boolean); } @@ -106,10 +116,6 @@ function walkExported(ast, data, addComment) { return newResults; } -function hasJSDocComment(path) { - return path.node.leadingComments && path.node.leadingComments.some(isJSDocComment); -} - function traverseExportedSubtree(path, data, addComments, overrideName) { var attachCommentPath = path; if (path.parentPath && path.parentPath.isExportDeclaration()) { diff --git a/test/fixture/document-exported.input.js b/test/fixture/document-exported.input.js index 5af071f09..0f4cffa5d 100644 --- a/test/fixture/document-exported.input.js +++ b/test/fixture/document-exported.input.js @@ -66,14 +66,16 @@ export type {T5} from './document-exported/x.js'; export var f4 = function(x: X) {} -var f5 = function(y: Y) {} + export {f5}; export var o1 = { om1() {} } -var o2 = { - om2() {} -} +/** f5 comment */ +var f5 = function(y: Y) {}, + o2 = { + om2() {} + }; export {o2}; diff --git a/test/fixture/document-exported.output.json b/test/fixture/document-exported.output.json index 2b0f875b6..b886f3cbc 100644 --- a/test/fixture/document-exported.output.json +++ b/test/fixture/document-exported.output.json @@ -1189,150 +1189,203 @@ "tags": [], "loc": { "start": { - "line": 69, - "column": 4 + "line": 72, + "column": 0 }, "end": { - "line": 69, - "column": 26 + "line": 74, + "column": 1 } }, "context": { "loc": { "start": { - "line": 69, - "column": 4 + "line": 72, + "column": 0 }, "end": { - "line": 69, - "column": 26 + "line": 74, + "column": 1 } } }, "errors": [], - "name": "f5", - "params": [ - { - "title": "param", - "name": "y", - "lineNumber": 69, - "type": { - "type": "NameExpression", - "name": "Y" - } - } - ], + "name": "o1", "members": { "instance": [], "static": [] }, "path": [ { - "name": "f5" + "name": "o1" } ], - "namespace": "f5" + "namespace": "o1" }, { "description": "", "tags": [], "loc": { "start": { - "line": 72, - "column": 0 + "line": 73, + "column": 2 }, "end": { - "line": 74, - "column": 1 + "line": 73, + "column": 10 } }, "context": { "loc": { "start": { - "line": 72, - "column": 0 + "line": 73, + "column": 2 }, "end": { - "line": 74, - "column": 1 + "line": 73, + "column": 10 } } }, "errors": [], - "name": "o1", + "name": "om1", + "kind": "function", "members": { "instance": [], "static": [] }, "path": [ { - "name": "o1" + "name": "om1", + "kind": "function" } ], - "namespace": "o1" + "namespace": "om1" }, { - "description": "", + "description": { + "type": "root", + "children": [ + { + "type": "paragraph", + "children": [ + { + "type": "text", + "value": "f5 comment", + "position": { + "start": { + "line": 1, + "column": 1, + "offset": 0 + }, + "end": { + "line": 1, + "column": 11, + "offset": 10 + }, + "indent": [] + } + } + ], + "position": { + "start": { + "line": 1, + "column": 1, + "offset": 0 + }, + "end": { + "line": 1, + "column": 11, + "offset": 10 + }, + "indent": [] + } + } + ], + "position": { + "start": { + "line": 1, + "column": 1, + "offset": 0 + }, + "end": { + "line": 1, + "column": 11, + "offset": 10 + } + } + }, "tags": [], "loc": { "start": { - "line": 73, - "column": 2 + "line": 76, + "column": 0 }, "end": { - "line": 73, - "column": 10 + "line": 76, + "column": 17 } }, "context": { "loc": { "start": { - "line": 73, - "column": 2 + "line": 77, + "column": 0 }, "end": { - "line": 73, - "column": 10 + "line": 80, + "column": 4 } } }, "errors": [], - "name": "om1", + "name": "f5", "kind": "function", + "params": [ + { + "title": "param", + "name": "y", + "lineNumber": 77, + "type": { + "type": "NameExpression", + "name": "Y" + } + } + ], "members": { "instance": [], "static": [] }, "path": [ { - "name": "om1", + "name": "f5", "kind": "function" } ], - "namespace": "om1" + "namespace": "f5" }, { "description": "", "tags": [], "loc": { "start": { - "line": 76, - "column": 4 + "line": 78, + "column": 2 }, "end": { - "line": 78, - "column": 1 + "line": 80, + "column": 3 } }, "context": { "loc": { "start": { - "line": 76, - "column": 4 + "line": 78, + "column": 2 }, "end": { - "line": 78, - "column": 1 + "line": 80, + "column": 3 } } }, @@ -1354,23 +1407,23 @@ "tags": [], "loc": { "start": { - "line": 77, - "column": 2 + "line": 79, + "column": 4 }, "end": { - "line": 77, - "column": 10 + "line": 79, + "column": 12 } }, "context": { "loc": { "start": { - "line": 77, - "column": 2 + "line": 79, + "column": 4 }, "end": { - "line": 77, - "column": 10 + "line": 79, + "column": 12 } } }, diff --git a/test/fixture/document-exported.output.md b/test/fixture/document-exported.output.md index cfd575c70..050ee4474 100644 --- a/test/fixture/document-exported.output.md +++ b/test/fixture/document-exported.output.md @@ -78,16 +78,18 @@ Returns **void** - `x` **X** +# o1 + +# om1 + # f5 +f5 comment + **Parameters** - `y` **Y** -# o1 - -# om1 - # o2 # om2 diff --git a/test/fixture/document-exported.output.md.json b/test/fixture/document-exported.output.md.json index 5bd9b84cf..ea3cff981 100644 --- a/test/fixture/document-exported.output.md.json +++ b/test/fixture/document-exported.output.md.json @@ -559,6 +559,26 @@ } ] }, + { + "depth": 1, + "type": "heading", + "children": [ + { + "type": "text", + "value": "o1" + } + ] + }, + { + "depth": 1, + "type": "heading", + "children": [ + { + "type": "text", + "value": "om1" + } + ] + }, { "depth": 1, "type": "heading", @@ -569,6 +589,41 @@ } ] }, + { + "type": "paragraph", + "children": [ + { + "type": "text", + "value": "f5 comment", + "position": { + "start": { + "line": 1, + "column": 1, + "offset": 0 + }, + "end": { + "line": 1, + "column": 11, + "offset": 10 + }, + "indent": [] + } + } + ], + "position": { + "start": { + "line": 1, + "column": 1, + "offset": 0 + }, + "end": { + "line": 1, + "column": 11, + "offset": 10 + }, + "indent": [] + } + }, { "type": "strong", "children": [ @@ -615,26 +670,6 @@ } ] }, - { - "depth": 1, - "type": "heading", - "children": [ - { - "type": "text", - "value": "o1" - } - ] - }, - { - "depth": 1, - "type": "heading", - "children": [ - { - "type": "text", - "value": "om1" - } - ] - }, { "depth": 1, "type": "heading", From a883d51ea7f6413ddb892127c487073a932da397 Mon Sep 17 00:00:00 2001 From: Erik Arvidsson Date: Fri, 21 Oct 2016 11:58:06 -0700 Subject: [PATCH 2/2] Remove extra if --- lib/extractors/exported.js | 2 -- 1 file changed, 2 deletions(-) diff --git a/lib/extractors/exported.js b/lib/extractors/exported.js index acc76dfc2..6b39c3d3a 100644 --- a/lib/extractors/exported.js +++ b/lib/extractors/exported.js @@ -34,9 +34,7 @@ function walkExported(ast, data, addComment) { if (t.isVariableDeclarator(path) && path.parentPath.get('declarations')[0] === path) { return getComments(data, path.parentPath); } - } - if (!comments.length) { var added = addBlankComment(data, path, path.node); return added ? [added] : []; }