From 21c79dcbc2f86fa77a532a8f25d746dde4985569 Mon Sep 17 00:00:00 2001
From: Ron Buckton <ron.buckton@microsoft.com>
Date: Thu, 19 Dec 2019 15:15:35 -0800
Subject: [PATCH] Adds the JSDoc 'see' tag

---
 tsdoc/src/details/StandardTags.ts  | 26 ++++++++++++++++++++++++++
 tsdoc/src/emitters/TSDocEmitter.ts |  1 +
 tsdoc/src/nodes/DocComment.ts      | 25 +++++++++++++++++++++++--
 tsdoc/src/parser/NodeParser.ts     |  2 ++
 4 files changed, 52 insertions(+), 2 deletions(-)

diff --git a/tsdoc/src/details/StandardTags.ts b/tsdoc/src/details/StandardTags.ts
index 10e55ff1..3ac281b4 100644
--- 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
index f11e2b9f..47d3f6db 100644
--- 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
index b6bb5f62..727ce318 100644
--- 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[];
 
   /**
@@ -109,6 +112,7 @@ export class DocComment extends DocNode {
     };
     this.modifierTagSet = new StandardModifierTagSet(modifierTagSetParameters);
 
+    this._seeBlocks = [];
     this._customBlocks = [];
   }
 
@@ -117,6 +121,13 @@ 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.
    */
@@ -124,6 +135,16 @@ export class DocComment extends DocNode {
     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.
    */
@@ -142,6 +163,7 @@ export class DocComment extends DocNode {
       this.typeParams.count > 0 ? this.typeParams : undefined,
       this.returnsBlock,
       ...this.customBlocks,
+      ...this.seeBlocks,
       this.inheritDocTag,
       ...this.modifierTagSet.nodes
     ];
@@ -169,5 +191,4 @@ export class DocComment extends DocNode {
 }
 
 // Circular reference
-import { TSDocEmitter } from '../emitters/TSDocEmitter';import { IModifierTagSetParameters } from '../details/ModifierTagSet';
-
+import { TSDocEmitter } from '../emitters/TSDocEmitter';
\ No newline at end of file
diff --git a/tsdoc/src/parser/NodeParser.ts b/tsdoc/src/parser/NodeParser.ts
index 7e5cbf82..0e187cc1 100644
--- 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);
     }