Skip to content

Commit b53f947

Browse files
tmcwtmcw
committed
Nest both properties and params. Fixes #164 
1 parent 51d4478 commit b53f947

File tree

10 files changed

+474
-73
lines changed

10 files changed

+474
-73
lines changed

‎index.js‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
'use strict';
22

33
var sort = require('./lib/sort'),
4-
nestParams = require('./lib/nest_params'),
4+
nest = require('./lib/nest'),
55
filterAccess = require('./lib/filter_access'),
66
filterJS = require('./lib/filter_js'),
77
dependency = require('./lib/input/dependency'),
@@ -98,7 +98,7 @@ module.exports = function (indexes, options, callback) {
9898
inferParams(),
9999
inferReturn(),
100100
inferMembership(),
101-
nestParams,
101+
nest,
102102
options.github ? github : noop
103103
))
104104
.filter(Boolean)

‎lib/nest.js‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
'use strict';
2+
3+
function nestTag(comment, tagName, target) {
4+
if (!comment[target]) {
5+
return comment;
6+
}
7+
8+
var result = [],
9+
index = {};
10+
11+
comment[target].forEach(function (tag) {
12+
index[tag.name] = tag;
13+
var parts = tag.name.split(/(\[\])?\./);
14+
if (parts.length > 1) {
15+
var parent = index[parts[0]];
16+
if (parent === undefined) {
17+
comment.errors.push({
18+
message: '@' + tagName + ' ' + tag.name + '\'s parent ' + parts[0] + ' not found',
19+
commentLineNumber: tag.lineNumber
20+
});
21+
result.push(tag);
22+
return;
23+
}
24+
parent.properties = parent.properties || [];
25+
parent.properties.push(tag);
26+
} else {
27+
result.push(tag);
28+
}
29+
});
30+
31+
comment[target] = result;
32+
33+
return comment;
34+
}
35+
36+
/**
37+
* Nests
38+
* [parameters with properties](http://usejsdoc.org/tags-param.html#parameters-with-properties).
39+
*
40+
* A parameter `employee.name` will be attached to the parent parameter `employee` in
41+
* a `properties` array.
42+
*
43+
* This assumes that incoming comments have been flattened.
44+
*
45+
* @param {Object} comment input comment
46+
* @return {Object} nested comment
47+
*/
48+
function nest(comment) {
49+
return nestTag(nestTag(comment, 'param', 'params'),
50+
'property', 'properties');
51+
}
52+
53+
module.exports = nest;

‎lib/nest_params.js‎

Lines changed: 0 additions & 48 deletions
This file was deleted.

‎lib/output/markdown_ast.js‎

Lines changed: 17 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -54,21 +54,26 @@ function commentsToAST(comments, opts, callback) {
5454
function propertySection(comment) {
5555
return !!comment.properties && [
5656
u('strong', [u('text', 'Properties')]),
57-
u('list', { ordered: false },
58-
comment.properties.map(function (property) {
59-
return u('listItem', [
60-
u('paragraph', [
61-
u('inlineCode', property.name),
62-
u('text', ' '),
63-
u('text', [u('text', formatType(property.type))]),
64-
u('text', ' '),
65-
mdast.parse(formatInlineTags(property.description))
66-
])
67-
].filter(Boolean))
68-
}))
57+
propertyList(comment.properties)
6958
];
7059
}
7160

61+
function propertyList(properties) {
62+
return u('list', { ordered: false },
63+
properties.map(function (property) {
64+
return u('listItem', [
65+
u('paragraph', [
66+
u('inlineCode', property.name),
67+
u('text', ' '),
68+
u('text', [u('text', formatType(property.type))]),
69+
u('text', ' '),
70+
mdast.parse(formatInlineTags(property.description))
71+
]),
72+
property.properties && propertyList(property.properties)
73+
].filter(Boolean))
74+
}));
75+
}
76+
7277
function examplesSection(comment) {
7378
return !!comment.examples && [u('strong', [u('text', 'Examples')])]
7479
.concat(comment.examples.map(function (example) {

‎test/fixture/nested_properties.input.js‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,5 +3,9 @@
33
* @param {Object} options some options
44
* @param {number} options.much how much
55
* @param {number} bar something else
6+
* @property {Object} theTime the current time
7+
* @property {number} theTime.hours
8+
* @property {number} theTime.minutes
9+
* @property {number} theTime.seconds
610
* @returns {Object} foo something else
711
*/

‎test/fixture/nested_properties.output.custom.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,5 +8,16 @@
88
- `bar` **number** something else
99

1010

11+
**Properties**
12+
13+
- `theTime` the current time
14+
15+
- `theTime.hours`
16+
17+
- `theTime.minutes`
18+
19+
- `theTime.seconds`
20+
21+
1122
Returns **Object** foo something else
1223

‎test/fixture/nested_properties.output.json‎

Lines changed: 120 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -50,10 +50,82 @@
5050
},
5151
"name": "bar"
5252
},
53+
{
54+
"title": "property",
55+
"description": "the current time",
56+
"lineNumber": 5,
57+
"type": {
58+
"type": "NameExpression",
59+
"name": "Object"
60+
},
61+
"name": "theTime",
62+
"properties": [
63+
{
64+
"title": "property",
65+
"description": null,
66+
"lineNumber": 6,
67+
"type": {
68+
"type": "NameExpression",
69+
"name": "number"
70+
},
71+
"name": "theTime.hours"
72+
},
73+
{
74+
"title": "property",
75+
"description": null,
76+
"lineNumber": 7,
77+
"type": {
78+
"type": "NameExpression",
79+
"name": "number"
80+
},
81+
"name": "theTime.minutes"
82+
},
83+
{
84+
"title": "property",
85+
"description": null,
86+
"lineNumber": 8,
87+
"type": {
88+
"type": "NameExpression",
89+
"name": "number"
90+
},
91+
"name": "theTime.seconds"
92+
}
93+
]
94+
},
95+
{
96+
"title": "property",
97+
"description": null,
98+
"lineNumber": 6,
99+
"type": {
100+
"type": "NameExpression",
101+
"name": "number"
102+
},
103+
"name": "theTime.hours"
104+
},
105+
{
106+
"title": "property",
107+
"description": null,
108+
"lineNumber": 7,
109+
"type": {
110+
"type": "NameExpression",
111+
"name": "number"
112+
},
113+
"name": "theTime.minutes"
114+
},
115+
{
116+
"title": "property",
117+
"description": null,
118+
"lineNumber": 8,
119+
"type": {
120+
"type": "NameExpression",
121+
"name": "number"
122+
},
123+
"name": "theTime.seconds"
124+
},
53125
{
54126
"title": "returns",
55127
"description": "foo something else",
56-
"lineNumber": 5,
128+
"lineNumber": 9,
57129
"type": {
58130
"type": "NameExpression",
59131
"name": "Object"
@@ -66,7 +138,7 @@
66138
"column": 0
67139
},
68140
"end": {
69-
"line": 7,
141+
"line": 11,
70142
"column": 3
71143
}
72144
},
@@ -77,7 +149,7 @@
77149
"column": 0
78150
},
79151
"end": {
80-
"line": 8,
152+
"line": 12,
81153
"column": 0
82154
}
83155
}
@@ -118,11 +190,55 @@
118190
"name": "bar"
119191
}
120192
],
193+
"properties": [
194+
{
195+
"title": "property",
196+
"description": "the current time",
197+
"lineNumber": 5,
198+
"type": {
199+
"type": "NameExpression",
200+
"name": "Object"
201+
},
202+
"name": "theTime",
203+
"properties": [
204+
{
205+
"title": "property",
206+
"description": null,
207+
"lineNumber": 6,
208+
"type": {
209+
"type": "NameExpression",
210+
"name": "number"
211+
},
212+
"name": "theTime.hours"
213+
},
214+
{
215+
"title": "property",
216+
"description": null,
217+
"lineNumber": 7,
218+
"type": {
219+
"type": "NameExpression",
220+
"name": "number"
221+
},
222+
"name": "theTime.minutes"
223+
},
224+
{
225+
"title": "property",
226+
"description": null,
227+
"lineNumber": 8,
228+
"type": {
229+
"type": "NameExpression",
230+
"name": "number"
231+
},
232+
"name": "theTime.seconds"
233+
}
234+
]
235+
}
236+
],
121237
"returns": [
122238
{
123239
"title": "returns",
124240
"description": "foo something else",
125-
"lineNumber": 5,
241+
"lineNumber": 9,
126242
"type": {
127243
"type": "NameExpression",
128244
"name": "Object"

‎test/fixture/nested_properties.output.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,5 +8,16 @@
88
- `bar` **number** something else
99

1010

11+
**Properties**
12+
13+
- `theTime` the current time
14+
15+
- `theTime.hours`
16+
17+
- `theTime.minutes`
18+
19+
- `theTime.seconds`
20+
21+
1122
Returns **Object** foo something else
1223

0 commit comments

Comments
 (0)