From a97a4ac39015a252608525bd186a1644df5ffa83 Mon Sep 17 00:00:00 2001 From: Hans Bergren Date: Fri, 8 May 2020 10:55:06 -0400 Subject: [PATCH 1/8] Add support for the see tag --- tsdoc/src/details/StandardTags.ts | 32 ++++++++++++++++++++++++++++++ tsdoc/src/emitters/TSDocEmitter.ts | 1 + tsdoc/src/nodes/DocComment.ts | 17 ++++++++++++++++ tsdoc/src/parser/NodeParser.ts | 3 +++ 4 files changed, 53 insertions(+) diff --git a/tsdoc/src/details/StandardTags.ts b/tsdoc/src/details/StandardTags.ts index 72ee1ac5..5b8fa623 100644 --- a/tsdoc/src/details/StandardTags.ts +++ b/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 diff --git a/tsdoc/src/emitters/TSDocEmitter.ts b/tsdoc/src/emitters/TSDocEmitter.ts index 44d6d125..83a9b2b0 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 36428446..c8393c0f 100644 --- a/tsdoc/src/nodes/DocComment.ts +++ b/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,6 +116,13 @@ export class DocComment extends DocNode { return DocNodeKind.Comment; } + /** + * The collection of all `@see` DockBlockTag nodes belonging to this doc comment. + */ + public get seeBlocks(): ReadonlyArray { + return this._seeBlocks; + } + /** * The collection of all DocBlock nodes belonging to this doc comment. */ @@ -121,6 +130,13 @@ export class DocComment extends DocNode { 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 ]; diff --git a/tsdoc/src/parser/NodeParser.ts b/tsdoc/src/parser/NodeParser.ts index 764611c1..3c1a432f 100644 --- a/tsdoc/src/parser/NodeParser.ts +++ b/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); } From 644ea51caa7fb54d01a2bb9851ba58548f69f2b2 Mon Sep 17 00:00:00 2001 From: Hans Bergren Date: Fri, 8 May 2020 13:08:31 -0400 Subject: [PATCH 2/8] Have a single way to use the `@see` tag with a `@link` --- tsdoc/src/details/StandardTags.ts | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/tsdoc/src/details/StandardTags.ts b/tsdoc/src/details/StandardTags.ts index 5b8fa623..8a4844f0 100644 --- a/tsdoc/src/details/StandardTags.ts +++ b/tsdoc/src/details/StandardTags.ts @@ -339,9 +339,8 @@ export class StandardTags { * * ```ts * /** - * * Both of these will link to the bar function. + * * Link to the bar function. * * @see {@link bar} - * * @see bar * */ * function foo() {} From b0b8fb54fb7daf46138826806611de17a7c4fb67 Mon Sep 17 00:00:00 2001 From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com> Date: Sat, 9 May 2020 21:48:43 -0700 Subject: [PATCH 3/8] Clarify spec based on conversation from https://github.com/microsoft/tsdoc/pull/205 --- tsdoc/src/details/StandardTags.ts | 44 +++++++++++++++++++++---------- 1 file changed, 30 insertions(+), 14 deletions(-) diff --git a/tsdoc/src/details/StandardTags.ts b/tsdoc/src/details/StandardTags.ts index 8a4844f0..b6e4d17f 100644 --- a/tsdoc/src/details/StandardTags.ts +++ b/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: @@ -331,7 +331,8 @@ export class StandardTags { /** * (Extended) * - * Used to document another symbol or resource that may be related to the current item being documented. + * Used build a list of references to an API item or other resource that may be related to the + * current item. * * @remarks * @@ -339,18 +340,33 @@ export class StandardTags { * * ```ts * /** - * * Link to the bar function. - * * @see {@link bar} + * * 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 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() {} + * 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', From 1369369d01066b2f0e513daf354f287314874ea3 Mon Sep 17 00:00:00 2001 From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com> Date: Sat, 9 May 2020 21:50:10 -0700 Subject: [PATCH 4/8] rush change --- .../tsdoc/hbergren-see-tag_2020-05-10-04-50.json | 11 +++++++++++ 1 file changed, 11 insertions(+) create mode 100644 common/changes/@microsoft/tsdoc/hbergren-see-tag_2020-05-10-04-50.json diff --git a/common/changes/@microsoft/tsdoc/hbergren-see-tag_2020-05-10-04-50.json b/common/changes/@microsoft/tsdoc/hbergren-see-tag_2020-05-10-04-50.json new file mode 100644 index 00000000..c490bea6 --- /dev/null +++ b/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" +} \ No newline at end of file From 037635cdca66524c6d39f6209afe994d71476ab4 Mon Sep 17 00:00:00 2001 From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com> Date: Sun, 10 May 2020 00:06:13 -0700 Subject: [PATCH 5/8] Update playground to render `@example` and `@see` blocks --- playground/src/DocHtmlView.tsx | 37 ++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/playground/src/DocHtmlView.tsx b/playground/src/DocHtmlView.tsx index fd0a0a39..b895e595 100644 --- a/playground/src/DocHtmlView.tsx +++ b/playground/src/DocHtmlView.tsx @@ -72,6 +72,43 @@ export class DocHtmlView extends React.Component { ); } + 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( + +

{heading}

+ { this._renderContainer(exampleBlock.content) } + + ); + + ++exampleNumber; + } + + if (docComment.seeBlocks.length > 0) { + const listItems: React.ReactNode[] = []; + for (const seeBlock of docComment.seeBlocks) { + listItems.push( +
  • + { this._renderContainer(seeBlock.content) } +
    • + ); + } + + outputElements.push( + +

    See Also

    +
      + {listItems} +
    +     + ); + } + const modifierTags: ReadonlyArray = docComment.modifierTagSet.nodes; if (modifierTags.length > 0) { From cdf8640f301bd784cfb8fd62f22c2526559da702 Mon Sep 17 00:00:00 2001 From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com> Date: Mon, 18 May 2020 12:08:20 -0700 Subject: [PATCH 6/8] Update tsdoc/src/details/StandardTags.ts Co-authored-by: Hans Bergren --- tsdoc/src/details/StandardTags.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tsdoc/src/details/StandardTags.ts b/tsdoc/src/details/StandardTags.ts index b6e4d17f..84c8984e 100644 --- a/tsdoc/src/details/StandardTags.ts +++ b/tsdoc/src/details/StandardTags.ts @@ -331,7 +331,7 @@ export class StandardTags { /** * (Extended) * - * Used build a list of references to an API item or other resource that may be related to the + * Used to build a list of references to an API item or other resource that may be related to the * current item. * * @remarks From 47c17be7e070b4724859fdca7790cbe90cee346e Mon Sep 17 00:00:00 2001 From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com> Date: Wed, 20 May 2020 15:23:11 -0700 Subject: [PATCH 7/8] Mark appendSeeBlock() as internal --- tsdoc/src/nodes/DocComment.ts | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/tsdoc/src/nodes/DocComment.ts b/tsdoc/src/nodes/DocComment.ts index c8393c0f..c48a6b46 100644 --- a/tsdoc/src/nodes/DocComment.ts +++ b/tsdoc/src/nodes/DocComment.ts @@ -132,8 +132,9 @@ export class DocComment extends DocNode { /** * Append an item to the seeBlocks collection. + * @internal */ - public appendSeeBlock(block: DocBlock): void { + public _appendSeeBlock(block: DocBlock): void { this._seeBlocks.push(block); } From 738354c43318b87a95f013921f6066a7e589fea4 Mon Sep 17 00:00:00 2001 From: Pete Gonzalez <4673363+octogonz@users.noreply.github.com> Date: Wed, 20 May 2020 15:25:15 -0700 Subject: [PATCH 8/8] Mark appendSeeBlock() as internal --- tsdoc/src/parser/NodeParser.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tsdoc/src/parser/NodeParser.ts b/tsdoc/src/parser/NodeParser.ts index 3c1a432f..67dd9750 100644 --- a/tsdoc/src/parser/NodeParser.ts +++ b/tsdoc/src/parser/NodeParser.ts @@ -330,7 +330,7 @@ export class NodeParser { docComment.returnsBlock = block; break; case StandardTags.see.tagNameWithUpperCase: - docComment.appendSeeBlock(block); + docComment._appendSeeBlock(block); break; default: docComment.appendCustomBlock(block);