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 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) { diff --git a/tsdoc/src/details/StandardTags.ts b/tsdoc/src/details/StandardTags.ts index 8a4844f..84c8984 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 to 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',