Skip to content

Commit 8a2ec3e

Browse files
tmcwtmcw
committed
Allow param tag type to be inferred and merged with description
1 parent 37abe4c commit 8a2ec3e

File tree

6 files changed

+324
-0
lines changed

6 files changed

+324
-0
lines changed

‎lib/infer/params.js‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -121,11 +121,20 @@ module.exports = function () {
121121

122122
path.value.params.forEach(function (param, j) {
123123
if (existingParams[param.name] === undefined) {
124+
// This type is not explicitly documented
124125
if (!comment.params) {
125126
comment.params = [];
126127
}
127128

128129
comment.params = comment.params.concat(paramToDoc(param, j));
130+
} else if (!existingParams[param.name].type) {
131+
// This param has a description, but potentially it can
132+
// be have an inferred type. Infer its type without
133+
// dropping the description.
134+
var doc = paramToDoc(param, j);
135+
if (doc.type) {
136+
existingParams[param.name].type = doc.type;
137+
}
129138
}
130139
paramOrder[param.name] = i++;
131140
});

‎test/fixture/merge-infered-type.input.js‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
/**
2+
* Add five to `x`.
3+
*
4+
* @param x The number to add five to.
5+
* @returns {number} x plus five.
6+
*/
7+
function addFive(x: number): number {
8+
return x + 5;
9+
}

‎test/fixture/merge-infered-type.output.custom.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# addFive
2+
3+
Add five to `x`.
4+
5+
**Parameters**
6+
7+
- `x` **number** The number to add five to.
8+
9+
Returns **number** x plus five.

‎test/fixture/merge-infered-type.output.json‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
[
2+
{
3+
"description": "Add five to `x`.",
4+
"tags": [
5+
{
6+
"title": "param",
7+
"description": "The number to add five to.",
8+
"lineNumber": 3,
9+
"type": {
10+
"type": "NameExpression",
11+
"name": "number"
12+
},
13+
"name": "x"
14+
},
15+
{
16+
"title": "returns",
17+
"description": "x plus five.",
18+
"lineNumber": 4,
19+
"type": {
20+
"type": "NameExpression",
21+
"name": "number"
22+
}
23+
}
24+
],
25+
"loc": {
26+
"start": {
27+
"line": 1,
28+
"column": 0
29+
},
30+
"end": {
31+
"line": 6,
32+
"column": 3
33+
}
34+
},
35+
"context": {
36+
"loc": {
37+
"start": {
38+
"line": 7,
39+
"column": 0
40+
},
41+
"end": {
42+
"line": 9,
43+
"column": 1
44+
}
45+
},
46+
"code": "/**\n * Add five to `x`.\n *\n * @param x The number to add five to.\n * @returns {number} x plus five.\n */\nfunction addFive(x: number): number {\n return x + 5;\n}\n"
47+
},
48+
"errors": [],
49+
"params": [
50+
{
51+
"title": "param",
52+
"description": "The number to add five to.",
53+
"lineNumber": 3,
54+
"type": {
55+
"type": "NameExpression",
56+
"name": "number"
57+
},
58+
"name": "x"
59+
}
60+
],
61+
"returns": [
62+
{
63+
"title": "returns",
64+
"description": "x plus five.",
65+
"lineNumber": 4,
66+
"type": {
67+
"type": "NameExpression",
68+
"name": "number"
69+
}
70+
}
71+
],
72+
"name": "addFive",
73+
"kind": "function",
74+
"members": {
75+
"instance": [],
76+
"static": []
77+
},
78+
"path": [
79+
"addFive"
80+
]
81+
}
82+
]

‎test/fixture/merge-infered-type.output.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# addFive
2+
3+
Add five to `x`.
4+
5+
**Parameters**
6+
7+
- `x` **number** The number to add five to.
8+
9+
Returns **number** x plus five.

‎test/fixture/merge-infered-type.output.md.json‎

Lines changed: 206 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,206 @@
1+
{
2+
"type": "root",
3+
"children": [
4+
{
5+
"depth": 1,
6+
"type": "heading",
7+
"children": [
8+
{
9+
"type": "text",
10+
"value": "addFive"
11+
}
12+
]
13+
},
14+
{
15+
"type": "paragraph",
16+
"children": [
17+
{
18+
"type": "text",
19+
"value": "Add five to ",
20+
"position": {
21+
"start": {
22+
"line": 1,
23+
"column": 1
24+
},
25+
"end": {
26+
"line": 1,
27+
"column": 13
28+
},
29+
"indent": []
30+
}
31+
},
32+
{
33+
"type": "inlineCode",
34+
"value": "x",
35+
"position": {
36+
"start": {
37+
"line": 1,
38+
"column": 13
39+
},
40+
"end": {
41+
"line": 1,
42+
"column": 16
43+
},
44+
"indent": []
45+
}
46+
},
47+
{
48+
"type": "text",
49+
"value": ".",
50+
"position": {
51+
"start": {
52+
"line": 1,
53+
"column": 16
54+
},
55+
"end": {
56+
"line": 1,
57+
"column": 17
58+
},
59+
"indent": []
60+
}
61+
}
62+
],
63+
"position": {
64+
"start": {
65+
"line": 1,
66+
"column": 1
67+
},
68+
"end": {
69+
"line": 1,
70+
"column": 17
71+
},
72+
"indent": []
73+
}
74+
},
75+
{
76+
"type": "strong",
77+
"children": [
78+
{
79+
"type": "text",
80+
"value": "Parameters"
81+
}
82+
]
83+
},
84+
{
85+
"ordered": false,
86+
"type": "list",
87+
"children": [
88+
{
89+
"type": "listItem",
90+
"children": [
91+
{
92+
"type": "paragraph",
93+
"children": [
94+
{
95+
"type": "inlineCode",
96+
"value": "x"
97+
},
98+
{
99+
"type": "text",
100+
"value": " "
101+
},
102+
{
103+
"type": "strong",
104+
"children": [
105+
{
106+
"type": "text",
107+
"value": "number"
108+
}
109+
]
110+
},
111+
{
112+
"type": "text",
113+
"value": " "
114+
},
115+
{
116+
"type": "paragraph",
117+
"children": [
118+
{
119+
"type": "text",
120+
"value": "The number to add five to.",
121+
"position": {
122+
"start": {
123+
"line": 1,
124+
"column": 1
125+
},
126+
"end": {
127+
"line": 1,
128+
"column": 27
129+
},
130+
"indent": []
131+
}
132+
}
133+
],
134+
"position": {
135+
"start": {
136+
"line": 1,
137+
"column": 1
138+
},
139+
"end": {
140+
"line": 1,
141+
"column": 27
142+
},
143+
"indent": []
144+
}
145+
}
146+
]
147+
}
148+
]
149+
}
150+
]
151+
},
152+
{
153+
"type": "paragraph",
154+
"children": [
155+
{
156+
"type": "text",
157+
"value": "Returns "
158+
},
159+
{
160+
"type": "strong",
161+
"children": [
162+
{
163+
"type": "text",
164+
"value": "number"
165+
}
166+
]
167+
},
168+
{
169+
"type": "text",
170+
"value": " "
171+
},
172+
{
173+
"type": "paragraph",
174+
"children": [
175+
{
176+
"type": "text",
177+
"value": "x plus five.",
178+
"position": {
179+
"start": {
180+
"line": 1,
181+
"column": 1
182+
},
183+
"end": {
184+
"line": 1,
185+
"column": 13
186+
},
187+
"indent": []
188+
}
189+
}
190+
],
191+
"position": {
192+
"start": {
193+
"line": 1,
194+
"column": 1
195+
},
196+
"end": {
197+
"line": 1,
198+
"column": 13
199+
},
200+
"indent": []
201+
}
202+
}
203+
]
204+
}
205+
]
206+
}

0 commit comments

Comments
 (0)