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
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<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) {
diff --git a/tsdoc/src/details/StandardTags.ts b/tsdoc/src/details/StandardTags.ts
index 72ee1ac5..84c8984e 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:
@@ -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
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..c48a6b46 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<DocBlock> {
+ return this._seeBlocks;
+ }
+
/**
* The collection of all DocBlock nodes belonging to this doc comment.
*/
@@ -121,6 +130,14 @@ export class DocComment extends DocNode {
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
];
diff --git a/tsdoc/src/parser/NodeParser.ts b/tsdoc/src/parser/NodeParser.ts
index 764611c1..67dd9750 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);
}