Skip to content

Commit f07285a

Browse files
tmcwtmcw
authored
feat(markdown): Add @see tag output in Markdown (#682)
Refs #673
1 parent 84c9215 commit f07285a

File tree

6 files changed

+408
-9
lines changed

6 files changed

+408
-9
lines changed

‎declarations/comment.js

+1-1
Original file line numberDiff line numberDiff line change
@@ -110,7 +110,7 @@ declare type Comment = {
110110
params: Array<CommentTag>,
111111
properties: Array<CommentTag>,
112112
returns: Array<CommentTag>,
113-
sees: Array<CommentTag>,
113+
sees: Array<Remark>,
114114
throws: Array<CommentTag>,
115115
todos: Array<CommentTag>,
116116

‎lib/output/markdown_ast.js

+11
Original file line numberDiff line numberDiff line change
@@ -162,6 +162,16 @@ function buildMarkdownAST(comments/*: Array<Comment> */, config/*: Documentation
162162
]);
163163
}
164164

165+
function seeLink(comment/*: Comment */) {
166+
return comment.sees.length > 0 && u('list', { ordered: false }, comment.sees.map(see =>
167+
u('listItem', [
168+
u('strong', [
169+
u('text', 'See: ')
170+
].concat(see.children))
171+
])
172+
));
173+
}
174+
165175
function githubLink(comment/*: Comment */) {
166176
return comment.context && comment.context.github && u('paragraph', [
167177
u('link', {
@@ -204,6 +214,7 @@ function buildMarkdownAST(comments/*: Array<Comment> */, config/*: Documentation
204214
return [u('heading', { depth }, [u('text', comment.name || '')])]
205215
.concat(githubLink(comment))
206216
.concat(augmentsLink(comment))
217+
.concat(seeLink(comment))
207218
.concat(comment.description ? comment.description.children : [])
208219
.concat(typeSection(comment))
209220
.concat(paramSection(comment))

‎test/fixture/meta.input.js

+3
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,9 @@
11
/**
22
* This function returns the number one.
33
* @returns {number} numberone
4+
* @see {@link http://github.com/|github}
5+
* @see TestCase
6+
* @see [markdown link](http://foo.com/)
47
* @version 1.0.0
58
* @since 2.0.0
69
* @copyright Tom MacWright

‎test/fixture/meta.output.json

+208-8
Original file line numberDiff line numberDiff line change
@@ -62,25 +62,40 @@
6262
"name": "number"
6363
}
6464
},
65+
{
66+
"title": "see",
67+
"description": "{@link http://github.com/|github}",
68+
"lineNumber": 3
69+
},
70+
{
71+
"title": "see",
72+
"description": "TestCase",
73+
"lineNumber": 4
74+
},
75+
{
76+
"title": "see",
77+
"description": "[markdown link](http://foo.com/)",
78+
"lineNumber": 5
79+
},
6580
{
6681
"title": "version",
6782
"description": "1.0.0",
68-
"lineNumber": 3
83+
"lineNumber": 6
6984
},
7085
{
7186
"title": "since",
7287
"description": "2.0.0",
73-
"lineNumber": 4
88+
"lineNumber": 7
7489
},
7590
{
7691
"title": "copyright",
7792
"description": "Tom MacWright",
78-
"lineNumber": 5
93+
"lineNumber": 8
7994
},
8095
{
8196
"title": "license",
8297
"description": "BSD",
83-
"lineNumber": 6
98+
"lineNumber": 9
8499
}
85100
],
86101
"loc": {
@@ -89,18 +104,18 @@
89104
"column": 0
90105
},
91106
"end": {
92-
"line": 8,
107+
"line": 11,
93108
"column": 3
94109
}
95110
},
96111
"context": {
97112
"loc": {
98113
"start": {
99-
"line": 9,
114+
"line": 12,
100115
"column": 0
101116
},
102117
"end": {
103-
"line": 12,
118+
"line": 15,
104119
"column": 2
105120
}
106121
}
@@ -171,7 +186,192 @@
171186
}
172187
}
173188
],
174-
"sees": [],
189+
"sees": [
190+
{
191+
"type": "root",
192+
"children": [
193+
{
194+
"type": "paragraph",
195+
"children": [
196+
{
197+
"type": "link",
198+
"url": "http://github.com/",
199+
"title": null,
200+
"jsdoc": true,
201+
"children": [
202+
{
203+
"type": "text",
204+
"value": "github"
205+
}
206+
],
207+
"position": {
208+
"start": {
209+
"line": 1,
210+
"column": 1,
211+
"offset": 0
212+
},
213+
"end": {
214+
"line": 1,
215+
"column": 34,
216+
"offset": 33
217+
},
218+
"indent": []
219+
}
220+
}
221+
],
222+
"position": {
223+
"start": {
224+
"line": 1,
225+
"column": 1,
226+
"offset": 0
227+
},
228+
"end": {
229+
"line": 1,
230+
"column": 34,
231+
"offset": 33
232+
},
233+
"indent": []
234+
}
235+
}
236+
],
237+
"position": {
238+
"start": {
239+
"line": 1,
240+
"column": 1,
241+
"offset": 0
242+
},
243+
"end": {
244+
"line": 1,
245+
"column": 34,
246+
"offset": 33
247+
}
248+
}
249+
},
250+
{
251+
"type": "root",
252+
"children": [
253+
{
254+
"type": "paragraph",
255+
"children": [
256+
{
257+
"type": "text",
258+
"value": "TestCase",
259+
"position": {
260+
"start": {
261+
"line": 1,
262+
"column": 1,
263+
"offset": 0
264+
},
265+
"end": {
266+
"line": 1,
267+
"column": 9,
268+
"offset": 8
269+
},
270+
"indent": []
271+
}
272+
}
273+
],
274+
"position": {
275+
"start": {
276+
"line": 1,
277+
"column": 1,
278+
"offset": 0
279+
},
280+
"end": {
281+
"line": 1,
282+
"column": 9,
283+
"offset": 8
284+
},
285+
"indent": []
286+
}
287+
}
288+
],
289+
"position": {
290+
"start": {
291+
"line": 1,
292+
"column": 1,
293+
"offset": 0
294+
},
295+
"end": {
296+
"line": 1,
297+
"column": 9,
298+
"offset": 8
299+
}
300+
}
301+
},
302+
{
303+
"type": "root",
304+
"children": [
305+
{
306+
"type": "paragraph",
307+
"children": [
308+
{
309+
"type": "link",
310+
"title": null,
311+
"url": "http://foo.com/",
312+
"children": [
313+
{
314+
"type": "text",
315+
"value": "markdown link",
316+
"position": {
317+
"start": {
318+
"line": 1,
319+
"column": 2,
320+
"offset": 1
321+
},
322+
"end": {
323+
"line": 1,
324+
"column": 15,
325+
"offset": 14
326+
},
327+
"indent": []
328+
}
329+
}
330+
],
331+
"position": {
332+
"start": {
333+
"line": 1,
334+
"column": 1,
335+
"offset": 0
336+
},
337+
"end": {
338+
"line": 1,
339+
"column": 33,
340+
"offset": 32
341+
},
342+
"indent": []
343+
}
344+
}
345+
],
346+
"position": {
347+
"start": {
348+
"line": 1,
349+
"column": 1,
350+
"offset": 0
351+
},
352+
"end": {
353+
"line": 1,
354+
"column": 33,
355+
"offset": 32
356+
},
357+
"indent": []
358+
}
359+
}
360+
],
361+
"position": {
362+
"start": {
363+
"line": 1,
364+
"column": 1,
365+
"offset": 0
366+
},
367+
"end": {
368+
"line": 1,
369+
"column": 33,
370+
"offset": 32
371+
}
372+
}
373+
}
374+
],
175375
"throws": [],
176376
"todos": [],
177377
"version": "1.0.0",

‎test/fixture/meta.output.md

+4
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,10 @@
66

77
## meta.input
88

9+
- **See: [github](http://github.com/)**
10+
- **See: TestCase**
11+
- **See: [markdown link](http://foo.com/)**
12+
913
This function returns the number one.
1014

1115
Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** numberone

0 commit comments

Comments
 (0)