feat(markdown): Add @see tag output in Markdown (#682)

Refs #673
documentationjs · Feb 24, 2017 · f07285a · f07285a
1 parent 84c9215
commit f07285a
Show file tree

Hide file tree

Showing 6 changed files with 408 additions and 9 deletions.
diff --git a/declarations/comment.js b/declarations/comment.js
@@ -110,7 +110,7 @@ declare type Comment = {
   params: Array<CommentTag>,
   properties: Array<CommentTag>,
   returns: Array<CommentTag>,
-  sees: Array<CommentTag>,
+  sees: Array<Remark>,
   throws: Array<CommentTag>,
   todos: Array<CommentTag>,
 

diff --git a/lib/output/markdown_ast.js b/lib/output/markdown_ast.js
@@ -162,6 +162,16 @@ function buildMarkdownAST(comments/*: Array<Comment> */, 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<Comment> */, 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
@@ -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
@@ -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
@@ -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