Adds the JSDoc 'see' tag

microsoft · Feb 3, 2020 · 06624b2 · 06624b2
1 parent 8c7ad21
commit 06624b2
Show file tree

Hide file tree

Showing 4 changed files with 50 additions and 0 deletions.
diff --git a/tsdoc/src/details/StandardTags.ts b/tsdoc/src/details/StandardTags.ts
@@ -319,6 +319,31 @@ 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
+   * /**
+   *  * Make a rectangle from two points.
+   *  *
+   *  * @see {@link Point}
+   *  &#42;/
+   * function makeRect(a: Point, b: Point): Rect;
+   * ```
+   */
+  public static readonly see: TSDocTagDefinition = StandardTags._defineTag({
+    tagName: '@see',
+    synonyms: ['@seeAlso'],
+    syntaxKind: TSDocTagSyntaxKind.BlockTag,
+    standardization: Standardization.Extended
+  });
+
   /**
    * (Extended)
    *
@@ -413,6 +438,7 @@ export class StandardTags {
     StandardTags.remarks,
     StandardTags.returns,
     StandardTags.sealed,
+    StandardTags.see,
     StandardTags.throws,
     StandardTags.typeParam,
     StandardTags.virtual

diff --git a/tsdoc/src/emitters/TSDocEmitter.ts b/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) {

diff --git a/tsdoc/src/nodes/DocComment.ts b/tsdoc/src/nodes/DocComment.ts
@@ -2,6 +2,7 @@ import { DocNode, DocNodeKind, IDocNodeParameters } from './DocNode';
 import { DocSection } from './DocSection';
 import { StandardModifierTagSet } from '../details/StandardModifierTagSet';
 import { IModifierTagSetParameters } from '../details/ModifierTagSet';
+import { StandardTags } from '../details/StandardTags';
 import { DocBlock } from './DocBlock';
 import { DocInheritDocTag } from './DocInheritDocTag';
 import { StringBuilder } from '../emitters/StringBuilder';
@@ -88,6 +89,7 @@ export class DocComment extends DocNode {
    */
   public readonly modifierTagSet: StandardModifierTagSet;
 
+  private _seeBlocks: DocBlock[];
   private _customBlocks: DocBlock[];
 
   /**
@@ -106,6 +108,7 @@ export class DocComment extends DocNode {
     this.returnsBlock = undefined;
     this.modifierTagSet = new StandardModifierTagSet({ configuration: this.configuration });
 
+    this._seeBlocks = [];
     this._customBlocks = [];
   }
 
@@ -114,13 +117,30 @@ export class DocComment extends DocNode {
     return DocNodeKind.Comment;
   }
 
+  /**
+   * The collection of all `@see` DocBlockTag 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 {
+    if (!StandardTags.see.isDefinitionOfTag(block.blockTag)) {
+      throw new Error("Provided block is not a @see block.");
+    }
+    this._seeBlocks.push(block);
+  }
+
   /**
    * Append an item to the customBlocks collection.
    */
@@ -139,6 +159,7 @@ export class DocComment extends DocNode {
       this.typeParams.count > 0 ? this.typeParams : undefined,
       this.returnsBlock,
       ...this.customBlocks,
+      ...this.seeBlocks,
       this.inheritDocTag,
       ...this.modifierTagSet.nodes
     ];

diff --git a/tsdoc/src/parser/NodeParser.ts b/tsdoc/src/parser/NodeParser.ts
@@ -323,6 +323,8 @@ export class NodeParser {
       docComment.deprecatedBlock = block;
     } else if (StandardTags.returns.isDefinitionOfTag(block.blockTag)) {
       docComment.returnsBlock = block;
+    } else if (StandardTags.see.isDefinitionOfTag(block.blockTag)) {
+      docComment.appendSeeBlock(block);
     } else {
       docComment.appendCustomBlock(block);
     }