Skip to content

Commit 7ea89ba

Browse files
arvarv
committed
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 documentationjs#570
1 parent 9e6bcef commit 7ea89ba

File tree

5 files changed

+193
-95
lines changed

5 files changed

+193
-95
lines changed

‎lib/extractors/exported.js

Lines changed: 12 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -27,11 +27,21 @@ function walkExported(ast, data, addComment) {
2727
}
2828

2929
function getComments(data, path) {
30-
if (!hasJSDocComment(path)) {
30+
var comments = (path.node.leadingComments || []).filter(isJSDocComment);
31+
32+
if (!comments.length) {
33+
// If this is the first declarator we check for comments on the VariableDeclaration.
34+
if (t.isVariableDeclarator(path) && path.parentPath.get('declarations')[0] === path) {
35+
return getComments(data, path.parentPath);
36+
}
37+
}
38+
39+
if (!comments.length) {
3140
var added = addBlankComment(data, path, path.node);
3241
return added ? [added] : [];
3342
}
34-
return path.node.leadingComments.filter(isJSDocComment).map(function (comment) {
43+
44+
return comments.map(function (comment) {
3545
return addComment(data, comment.value, comment.loc, path, path.node.loc, true);
3646
}).filter(Boolean);
3747
}
@@ -106,10 +116,6 @@ function walkExported(ast, data, addComment) {
106116
return newResults;
107117
}
108118

109-
function hasJSDocComment(path) {
110-
return path.node.leadingComments && path.node.leadingComments.some(isJSDocComment);
111-
}
112-
113119
function traverseExportedSubtree(path, data, addComments, overrideName) {
114120
var attachCommentPath = path;
115121
if (path.parentPath && path.parentPath.isExportDeclaration()) {

‎test/fixture/document-exported.input.js

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -66,14 +66,16 @@ export type {T5} from './document-exported/x.js';
6666

6767
export var f4 = function(x: X) {}
6868

69-
var f5 = function(y: Y) {}
69+
7070
export {f5};
7171

7272
export var o1 = {
7373
om1() {}
7474
}
7575

76-
var o2 = {
77-
om2() {}
78-
}
76+
/** f5 comment */
77+
var f5 = function(y: Y) {},
78+
o2 = {
79+
om2() {}
80+
};
7981
export {o2};

‎test/fixture/document-exported.output.json

Lines changed: 114 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -1189,150 +1189,203 @@
11891189
"tags": [],
11901190
"loc": {
11911191
"start": {
1192-
"line": 69,
1193-
"column": 4
1192+
"line": 72,
1193+
"column": 0
11941194
},
11951195
"end": {
1196-
"line": 69,
1197-
"column": 26
1196+
"line": 74,
1197+
"column": 1
11981198
}
11991199
},
12001200
"context": {
12011201
"loc": {
12021202
"start": {
1203-
"line": 69,
1204-
"column": 4
1203+
"line": 72,
1204+
"column": 0
12051205
},
12061206
"end": {
1207-
"line": 69,
1208-
"column": 26
1207+
"line": 74,
1208+
"column": 1
12091209
}
12101210
}
12111211
},
12121212
"errors": [],
1213-
"name": "f5",
1214-
"params": [
1215-
{
1216-
"title": "param",
1217-
"name": "y",
1218-
"lineNumber": 69,
1219-
"type": {
1220-
"type": "NameExpression",
1221-
"name": "Y"
1222-
}
1223-
}
1224-
],
1213+
"name": "o1",
12251214
"members": {
12261215
"instance": [],
12271216
"static": []
12281217
},
12291218
"path": [
12301219
{
1231-
"name": "f5"
1220+
"name": "o1"
12321221
}
12331222
],
1234-
"namespace": "f5"
1223+
"namespace": "o1"
12351224
},
12361225
{
12371226
"description": "",
12381227
"tags": [],
12391228
"loc": {
12401229
"start": {
1241-
"line": 72,
1242-
"column": 0
1230+
"line": 73,
1231+
"column": 2
12431232
},
12441233
"end": {
1245-
"line": 74,
1246-
"column": 1
1234+
"line": 73,
1235+
"column": 10
12471236
}
12481237
},
12491238
"context": {
12501239
"loc": {
12511240
"start": {
1252-
"line": 72,
1253-
"column": 0
1241+
"line": 73,
1242+
"column": 2
12541243
},
12551244
"end": {
1256-
"line": 74,
1257-
"column": 1
1245+
"line": 73,
1246+
"column": 10
12581247
}
12591248
}
12601249
},
12611250
"errors": [],
1262-
"name": "o1",
1251+
"name": "om1",
1252+
"kind": "function",
12631253
"members": {
12641254
"instance": [],
12651255
"static": []
12661256
},
12671257
"path": [
12681258
{
1269-
"name": "o1"
1259+
"name": "om1",
1260+
"kind": "function"
12701261
}
12711262
],
1272-
"namespace": "o1"
1263+
"namespace": "om1"
12731264
},
12741265
{
1275-
"description": "",
1266+
"description": {
1267+
"type": "root",
1268+
"children": [
1269+
{
1270+
"type": "paragraph",
1271+
"children": [
1272+
{
1273+
"type": "text",
1274+
"value": "f5 comment",
1275+
"position": {
1276+
"start": {
1277+
"line": 1,
1278+
"column": 1,
1279+
"offset": 0
1280+
},
1281+
"end": {
1282+
"line": 1,
1283+
"column": 11,
1284+
"offset": 10
1285+
},
1286+
"indent": []
1287+
}
1288+
}
1289+
],
1290+
"position": {
1291+
"start": {
1292+
"line": 1,
1293+
"column": 1,
1294+
"offset": 0
1295+
},
1296+
"end": {
1297+
"line": 1,
1298+
"column": 11,
1299+
"offset": 10
1300+
},
1301+
"indent": []
1302+
}
1303+
}
1304+
],
1305+
"position": {
1306+
"start": {
1307+
"line": 1,
1308+
"column": 1,
1309+
"offset": 0
1310+
},
1311+
"end": {
1312+
"line": 1,
1313+
"column": 11,
1314+
"offset": 10
1315+
}
1316+
}
1317+
},
12761318
"tags": [],
12771319
"loc": {
12781320
"start": {
1279-
"line": 73,
1280-
"column": 2
1321+
"line": 76,
1322+
"column": 0
12811323
},
12821324
"end": {
1283-
"line": 73,
1284-
"column": 10
1325+
"line": 76,
1326+
"column": 17
12851327
}
12861328
},
12871329
"context": {
12881330
"loc": {
12891331
"start": {
1290-
"line": 73,
1291-
"column": 2
1332+
"line": 77,
1333+
"column": 0
12921334
},
12931335
"end": {
1294-
"line": 73,
1295-
"column": 10
1336+
"line": 80,
1337+
"column": 4
12961338
}
12971339
}
12981340
},
12991341
"errors": [],
1300-
"name": "om1",
1342+
"name": "f5",
13011343
"kind": "function",
1344+
"params": [
1345+
{
1346+
"title": "param",
1347+
"name": "y",
1348+
"lineNumber": 77,
1349+
"type": {
1350+
"type": "NameExpression",
1351+
"name": "Y"
1352+
}
1353+
}
1354+
],
13021355
"members": {
13031356
"instance": [],
13041357
"static": []
13051358
},
13061359
"path": [
13071360
{
1308-
"name": "om1",
1361+
"name": "f5",
13091362
"kind": "function"
13101363
}
13111364
],
1312-
"namespace": "om1"
1365+
"namespace": "f5"
13131366
},
13141367
{
13151368
"description": "",
13161369
"tags": [],
13171370
"loc": {
13181371
"start": {
1319-
"line": 76,
1320-
"column": 4
1372+
"line": 78,
1373+
"column": 2
13211374
},
13221375
"end": {
1323-
"line": 78,
1324-
"column": 1
1376+
"line": 80,
1377+
"column": 3
13251378
}
13261379
},
13271380
"context": {
13281381
"loc": {
13291382
"start": {
1330-
"line": 76,
1331-
"column": 4
1383+
"line": 78,
1384+
"column": 2
13321385
},
13331386
"end": {
1334-
"line": 78,
1335-
"column": 1
1387+
"line": 80,
1388+
"column": 3
13361389
}
13371390
}
13381391
},
@@ -1354,23 +1407,23 @@
13541407
"tags": [],
13551408
"loc": {
13561409
"start": {
1357-
"line": 77,
1358-
"column": 2
1410+
"line": 79,
1411+
"column": 4
13591412
},
13601413
"end": {
1361-
"line": 77,
1362-
"column": 10
1414+
"line": 79,
1415+
"column": 12
13631416
}
13641417
},
13651418
"context": {
13661419
"loc": {
13671420
"start": {
1368-
"line": 77,
1369-
"column": 2
1421+
"line": 79,
1422+
"column": 4
13701423
},
13711424
"end": {
1372-
"line": 77,
1373-
"column": 10
1425+
"line": 79,
1426+
"column": 12
13741427
}
13751428
}
13761429
},

‎test/fixture/document-exported.output.md

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -78,16 +78,18 @@ Returns **void**
7878

7979
- `x` **X**
8080

81+
# o1
82+
83+
# om1
84+
8185
# f5
8286

87+
f5 comment
88+
8389
**Parameters**
8490

8591
- `y` **Y**
8692

87-
# o1
88-
89-
# om1
90-
9193
# o2
9294

9395
# om2

0 commit comments

Comments
 (0)