Add support for the see tag

Author: 0xCLARITY

tsdoc/src/details/StandardTags.ts

@@ -328,6 +328,37 @@ export class StandardTags {
     standardization: Standardization.Extended
   });
 
+  /**
+   * (Extended)
+   *
+   * Used to document another symbol or resource that may be related to the current item being documented.
+   *
+   * @remarks
+   *
+   * For example:
+   *
+   * ```ts
+   * /**
+   *  * Both of these will link to the bar function.
+   *  * @see {@link bar}
+   *  * @see bar
+   *  */
+   * function foo() {}
+
+   * // Use the inline {@link} tag to include a link within a free-form description.
+   * /**
+   *  * @see {@link foo} for further information.
+   *  * @see {@link http://github.com|GitHub}
+   *  */
+   * function bar() {}
+   * ```
+   */
+  public static readonly see: TSDocTagDefinition = StandardTags._defineTag({
+    tagName: '@see',
+    syntaxKind: TSDocTagSyntaxKind.BlockTag,
+    standardization: Standardization.Extended
+  });
+
   /**
    * (Extended)
    *
@@ -420,6 +451,7 @@ export class StandardTags {
     StandardTags.remarks,
     StandardTags.returns,
     StandardTags.sealed,
+    StandardTags.see,
     StandardTags.throws,
     StandardTags.typeParam,
     StandardTags.virtual

tsdoc/src/emitters/TSDocEmitter.ts

@@ -130,6 +130,7 @@ export class TSDocEmitter {
           docComment.typeParams,
           docComment.returnsBlock,
           ...docComment.customBlocks,
+          ...docComment.seeBlocks,
           docComment.inheritDocTag
         ]);
         if (docComment.modifierTagSet.nodes.length > 0) {

tsdoc/src/nodes/DocComment.ts

@@ -87,6 +87,7 @@ export class DocComment extends DocNode {
    */
   public readonly modifierTagSet: StandardModifierTagSet;
 
+  private _seeBlocks: DocBlock[];
   private _customBlocks: DocBlock[];
 
   /**
@@ -106,6 +107,7 @@ export class DocComment extends DocNode {
 
     this.modifierTagSet = new StandardModifierTagSet();
 
+    this._seeBlocks = []
     this._customBlocks = [];
   }
 
@@ -114,13 +116,27 @@ export class DocComment extends DocNode {
     return DocNodeKind.Comment;
   }
 
+  /**
+   * The collection of all `@see` DockBlockTag nodes belonging to this doc comment.
+   */
+  public get seeBlocks(): ReadonlyArray<DocBlock> {
+    return this._seeBlocks;
+  }
+
   /**
    * The collection of all DocBlock nodes belonging to this doc comment.
    */
   public get customBlocks(): ReadonlyArray<DocBlock> {
     return this._customBlocks;
   }
 
+  /**
+   * Append an item to the seeBlocks collection.
+   */
+  public appendSeeBlock(block: DocBlock): void {
+    this._seeBlocks.push(block);
+  }
+
   /**
    * Append an item to the customBlocks collection.
    */
@@ -139,6 +155,7 @@ export class DocComment extends DocNode {
       this.typeParams.count > 0 ? this.typeParams : undefined,
       this.returnsBlock,
       ...this.customBlocks,
+      ...this.seeBlocks,
       this.inheritDocTag,
       ...this.modifierTagSet.nodes
     ];

tsdoc/src/parser/NodeParser.ts

@@ -329,6 +329,9 @@ export class NodeParser {
       case StandardTags.returns.tagNameWithUpperCase:
         docComment.returnsBlock = block;
         break;
+      case StandardTags.see.tagNameWithUpperCase:
+        docComment.appendSeeBlock(block);
+        break;
       default:
         docComment.appendCustomBlock(block);
     }