Adds the JSDoc 'see' tag

microsoft · Dec 19, 2019 · 70614b4 · 70614b4
1 parent eac58d3
commit 70614b4
Show file tree

Hide file tree

Showing 4 changed files with 52 additions and 2 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
@@ -5,6 +5,8 @@ import { DocBlock } from './DocBlock';
 import { DocInheritDocTag } from './DocInheritDocTag';
 import { StringBuilder } from '../emitters/StringBuilder';
 import { DocParamCollection } from './DocParamCollection';
+import { IModifierTagSetParameters } from '../details/ModifierTagSet';
+import { StandardTags } from '../details/StandardTags';
 
 /**
  * Constructor parameters for {@link DocComment}.
@@ -87,6 +89,7 @@ export class DocComment extends DocNode {
    */
   public readonly modifierTagSet: StandardModifierTagSet;
 
+  private _seeBlocks: DocBlock[];
   private _customBlocks: DocBlock[];
 
   /**
@@ -105,6 +108,7 @@ export class DocComment extends DocNode {
     this.returnsBlock = undefined;
     this.modifierTagSet = new StandardModifierTagSet({ configuration: this.configuration });
 
+    this._seeBlocks = [];
     this._customBlocks = [];
   }
 
@@ -113,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.
    */
@@ -138,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
     ];
@@ -165,5 +187,4 @@ export class DocComment extends DocNode {
 }
 
 // Circular reference
-import { TSDocEmitter } from '../emitters/TSDocEmitter';import { IModifierTagSetParameters } from '../details/ModifierTagSet';
-
+import { TSDocEmitter } from '../emitters/TSDocEmitter';
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);
     }