Merge pull request #236 from hbergren/see-tag

Add support for the `@see` tag

common/changes/@microsoft/tsdoc/hbergren-see-tag_2020-05-10-04-50.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/tsdoc",
+      "comment": "Add support for `@see` tag",
+      "type": "patch"
+    }
+  ],
+  "packageName": "@microsoft/tsdoc",
+  "email": "hansbergren@gmail.com"
+}

playground/src/DocHtmlView.tsx

@@ -72,6 +72,43 @@ export class DocHtmlView extends React.Component<IDocHtmlViewProps> {
       );
     }
 
+    const exampleBlocks: tsdoc.DocBlock[] = docComment.customBlocks.filter(x => x.blockTag.tagNameWithUpperCase
+      === tsdoc.StandardTags.example.tagNameWithUpperCase);
+
+    let exampleNumber: number = 1;
+    for (const exampleBlock of exampleBlocks) {
+      const heading: string = exampleBlocks.length > 1 ? `Example ${exampleNumber}` : 'Example';
+
+      outputElements.push(
+        <React.Fragment key='seeAlso'>
+          <h2 className='doc-heading'>{heading}</h2>
+          { this._renderContainer(exampleBlock.content) }
+        </React.Fragment>
+      );
+
+      ++exampleNumber;
+    }
+
+    if (docComment.seeBlocks.length > 0) {
+      const listItems: React.ReactNode[] = [];
+      for (const seeBlock of docComment.seeBlocks) {
+        listItems.push(
+          <li key={`item_${listItems.length}`}>
+            { this._renderContainer(seeBlock.content) }
+          </li>
+        );
+      }
+
+      outputElements.push(
+        <React.Fragment key='seeAlso'>
+          <h2 className='doc-heading'>See Also</h2>
+          <ul>
+            {listItems}
+          </ul>
+        </React.Fragment>
+      );
+    }
+
     const modifierTags: ReadonlyArray<tsdoc.DocBlockTag> = docComment.modifierTagSet.nodes;
 
     if (modifierTags.length > 0) {

tsdoc/src/details/StandardTags.ts

@@ -125,15 +125,15 @@ export class StandardTags {
    * separate NPM package.
    *
    * What gets copied
-   * 
-   * The `@inheritDoc` tag does not copy the entire comment body. Only the following 
+   *
+   * The `@inheritDoc` tag does not copy the entire comment body. Only the following
    * components are copied:
    * - summary section
    * - `@remarks` block
    * - `@params` blocks
    * - `@typeParam` blocks
    * - `@returns` block
-   * Other tags such as `@defaultValue` or `@example` are not copied, and need to be 
+   * Other tags such as `@defaultValue` or `@example` are not copied, and need to be
    * explicitly included after the `@inheritDoc` tag.
    *
    * TODO: The notation for API item references is still being standardized.  See this issue:
@@ -328,6 +328,52 @@ export class StandardTags {
     standardization: Standardization.Extended
   });
 
+  /**
+   * (Extended)
+   *
+   * Used to build a list of references to an API item or other resource that may be related to the
+   * current item.
+   *
+   * @remarks
+   *
+   * For example:
+   *
+   * ```ts
+   * /**
+   *  * Parses a string containing a Uniform Resource Locator (URL).
+   *  * @see {@link ParsedUrl} for the returned data structure
+   *  * @see {@link https://tools.ietf.org/html/rfc1738|RFC 1738}
+   *  * for syntax
+   *  * @see your developer SDK for code samples
+   *  * @param url - the string to be parsed
+   *  * @returns the parsed result
+   *  */
+   * function parseURL(url: string): ParsedUrl;
+   * ```
+   *
+   * `@see` is a block tag.  Each block becomes an item in the list of references.  For example, a documentation
+   * system might render the above blocks as follows:
+   *
+   * ```markdown
+   * `function parseURL(url: string): ParsedUrl;`
+   *
+   * Parses a string containing a Uniform Resource Locator (URL).
+   *
+   * ## See Also
+   * - ParsedUrl for the returned data structure
+   * - RFC 1738 for syntax
+   * - your developer SDK for code samples
+   * ```
+   *
+   * NOTE: JSDoc attempts to automatically hyperlink the text immediately after `@see`.  Because this is ambiguous
+   * with plain text, TSDoc instead requires an explicit `{@link}` tag to make hyperlinks.
+   */
+  public static readonly see: TSDocTagDefinition = StandardTags._defineTag({
+    tagName: '@see',
+    syntaxKind: TSDocTagSyntaxKind.BlockTag,
+    standardization: Standardization.Extended
+  });
+
   /**
    * (Extended)
    *
@@ -420,6 +466,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,28 @@ 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.
+   * @internal
+   */
+  public _appendSeeBlock(block: DocBlock): void {
+    this._seeBlocks.push(block);
+  }
+
   /**
    * Append an item to the customBlocks collection.
    */
@@ -139,6 +156,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);
     }