diff --git a/declarations/comment.js b/declarations/comment.js index 64268e630..1f8924f4b 100644 --- a/declarations/comment.js +++ b/declarations/comment.js @@ -110,7 +110,7 @@ declare type Comment = { params: Array, properties: Array, returns: Array, - sees: Array, + sees: Array, throws: Array, todos: Array, diff --git a/lib/output/markdown_ast.js b/lib/output/markdown_ast.js index 4058603f4..b93e6a776 100644 --- a/lib/output/markdown_ast.js +++ b/lib/output/markdown_ast.js @@ -162,6 +162,16 @@ function buildMarkdownAST(comments/*: Array */, config/*: Documentation ]); } + function seeLink(comment/*: Comment */) { + return comment.sees.length > 0 && u('list', { ordered: false }, comment.sees.map(see => + u('listItem', [ + u('strong', [ + u('text', 'See: ') + ].concat(see.children)) + ]) + )); + } + function githubLink(comment/*: Comment */) { return comment.context && comment.context.github && u('paragraph', [ u('link', { @@ -204,6 +214,7 @@ function buildMarkdownAST(comments/*: Array */, config/*: Documentation return [u('heading', { depth }, [u('text', comment.name || '')])] .concat(githubLink(comment)) .concat(augmentsLink(comment)) + .concat(seeLink(comment)) .concat(comment.description ? comment.description.children : []) .concat(typeSection(comment)) .concat(paramSection(comment)) diff --git a/test/fixture/meta.input.js b/test/fixture/meta.input.js index adfd4fdd0..890aa7615 100644 --- a/test/fixture/meta.input.js +++ b/test/fixture/meta.input.js @@ -1,6 +1,9 @@ /** * This function returns the number one. * @returns {number} numberone + * @see {@link http://github.com/|github} + * @see TestCase + * @see [markdown link](http://foo.com/) * @version 1.0.0 * @since 2.0.0 * @copyright Tom MacWright diff --git a/test/fixture/meta.output.json b/test/fixture/meta.output.json index 8181094f5..38acd1703 100644 --- a/test/fixture/meta.output.json +++ b/test/fixture/meta.output.json @@ -62,25 +62,40 @@ "name": "number" } }, + { + "title": "see", + "description": "{@link http://github.com/|github}", + "lineNumber": 3 + }, + { + "title": "see", + "description": "TestCase", + "lineNumber": 4 + }, + { + "title": "see", + "description": "[markdown link](http://foo.com/)", + "lineNumber": 5 + }, { "title": "version", "description": "1.0.0", - "lineNumber": 3 + "lineNumber": 6 }, { "title": "since", "description": "2.0.0", - "lineNumber": 4 + "lineNumber": 7 }, { "title": "copyright", "description": "Tom MacWright", - "lineNumber": 5 + "lineNumber": 8 }, { "title": "license", "description": "BSD", - "lineNumber": 6 + "lineNumber": 9 } ], "loc": { @@ -89,18 +104,18 @@ "column": 0 }, "end": { - "line": 8, + "line": 11, "column": 3 } }, "context": { "loc": { "start": { - "line": 9, + "line": 12, "column": 0 }, "end": { - "line": 12, + "line": 15, "column": 2 } } @@ -171,7 +186,192 @@ } } ], - "sees": [], + "sees": [ + { + "type": "root", + "children": [ + { + "type": "paragraph", + "children": [ + { + "type": "link", + "url": "http://github.com/", + "title": null, + "jsdoc": true, + "children": [ + { + "type": "text", + "value": "github" + } + ], + "position": { + "start": { + "line": 1, + "column": 1, + "offset": 0 + }, + "end": { + "line": 1, + "column": 34, + "offset": 33 + }, + "indent": [] + } + } + ], + "position": { + "start": { + "line": 1, + "column": 1, + "offset": 0 + }, + "end": { + "line": 1, + "column": 34, + "offset": 33 + }, + "indent": [] + } + } + ], + "position": { + "start": { + "line": 1, + "column": 1, + "offset": 0 + }, + "end": { + "line": 1, + "column": 34, + "offset": 33 + } + } + }, + { + "type": "root", + "children": [ + { + "type": "paragraph", + "children": [ + { + "type": "text", + "value": "TestCase", + "position": { + "start": { + "line": 1, + "column": 1, + "offset": 0 + }, + "end": { + "line": 1, + "column": 9, + "offset": 8 + }, + "indent": [] + } + } + ], + "position": { + "start": { + "line": 1, + "column": 1, + "offset": 0 + }, + "end": { + "line": 1, + "column": 9, + "offset": 8 + }, + "indent": [] + } + } + ], + "position": { + "start": { + "line": 1, + "column": 1, + "offset": 0 + }, + "end": { + "line": 1, + "column": 9, + "offset": 8 + } + } + }, + { + "type": "root", + "children": [ + { + "type": "paragraph", + "children": [ + { + "type": "link", + "title": null, + "url": "http://foo.com/", + "children": [ + { + "type": "text", + "value": "markdown link", + "position": { + "start": { + "line": 1, + "column": 2, + "offset": 1 + }, + "end": { + "line": 1, + "column": 15, + "offset": 14 + }, + "indent": [] + } + } + ], + "position": { + "start": { + "line": 1, + "column": 1, + "offset": 0 + }, + "end": { + "line": 1, + "column": 33, + "offset": 32 + }, + "indent": [] + } + } + ], + "position": { + "start": { + "line": 1, + "column": 1, + "offset": 0 + }, + "end": { + "line": 1, + "column": 33, + "offset": 32 + }, + "indent": [] + } + } + ], + "position": { + "start": { + "line": 1, + "column": 1, + "offset": 0 + }, + "end": { + "line": 1, + "column": 33, + "offset": 32 + } + } + } + ], "throws": [], "todos": [], "version": "1.0.0", diff --git a/test/fixture/meta.output.md b/test/fixture/meta.output.md index 8e262387f..d45e106d4 100644 --- a/test/fixture/meta.output.md +++ b/test/fixture/meta.output.md @@ -6,6 +6,10 @@ ## meta.input +- **See: [github](http://github.com/)** +- **See: TestCase** +- **See: [markdown link](http://foo.com/)** + This function returns the number one. Returns **[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)** numberone diff --git a/test/fixture/meta.output.md.json b/test/fixture/meta.output.md.json index 451588533..d8cdaee45 100644 --- a/test/fixture/meta.output.md.json +++ b/test/fixture/meta.output.md.json @@ -15,6 +15,187 @@ } ] }, + { + "ordered": false, + "type": "list", + "children": [ + { + "type": "listItem", + "children": [ + { + "type": "strong", + "children": [ + { + "type": "text", + "value": "See: " + }, + { + "type": "paragraph", + "children": [ + { + "type": "link", + "url": "http://github.com/", + "title": null, + "jsdoc": true, + "children": [ + { + "type": "text", + "value": "github" + } + ], + "position": { + "start": { + "line": 1, + "column": 1, + "offset": 0 + }, + "end": { + "line": 1, + "column": 34, + "offset": 33 + }, + "indent": [] + } + } + ], + "position": { + "start": { + "line": 1, + "column": 1, + "offset": 0 + }, + "end": { + "line": 1, + "column": 34, + "offset": 33 + }, + "indent": [] + } + } + ] + } + ] + }, + { + "type": "listItem", + "children": [ + { + "type": "strong", + "children": [ + { + "type": "text", + "value": "See: " + }, + { + "type": "paragraph", + "children": [ + { + "type": "text", + "value": "TestCase", + "position": { + "start": { + "line": 1, + "column": 1, + "offset": 0 + }, + "end": { + "line": 1, + "column": 9, + "offset": 8 + }, + "indent": [] + } + } + ], + "position": { + "start": { + "line": 1, + "column": 1, + "offset": 0 + }, + "end": { + "line": 1, + "column": 9, + "offset": 8 + }, + "indent": [] + } + } + ] + } + ] + }, + { + "type": "listItem", + "children": [ + { + "type": "strong", + "children": [ + { + "type": "text", + "value": "See: " + }, + { + "type": "paragraph", + "children": [ + { + "type": "link", + "title": null, + "url": "http://foo.com/", + "children": [ + { + "type": "text", + "value": "markdown link", + "position": { + "start": { + "line": 1, + "column": 2, + "offset": 1 + }, + "end": { + "line": 1, + "column": 15, + "offset": 14 + }, + "indent": [] + } + } + ], + "position": { + "start": { + "line": 1, + "column": 1, + "offset": 0 + }, + "end": { + "line": 1, + "column": 33, + "offset": 32 + }, + "indent": [] + } + } + ], + "position": { + "start": { + "line": 1, + "column": 1, + "offset": 0 + }, + "end": { + "line": 1, + "column": 33, + "offset": 32 + }, + "indent": [] + } + } + ] + } + ] + } + ] + }, { "type": "paragraph", "children": [