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 1/4] 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 8a4844f..b6e4d17 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 2/4] 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 0000000..c490bea --- /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 3/4] 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 fd0a0a3..b895e59 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

    + +     + ); + } + 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 4/4] 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 b6e4d17..84c8984 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