diff --git a/tsdoc/src/details/StandardTags.ts b/tsdoc/src/details/StandardTags.ts index 10e55ff1..3ac281b4 100644 --- a/tsdoc/src/details/StandardTags.ts +++ b/tsdoc/src/details/StandardTags.ts @@ -319,6 +319,31 @@ 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 + * /** + * * Make a rectangle from two points. + * * + * * @see {@link Point} + * */ + * function makeRect(a: Point, b: Point): Rect; + * ``` + */ + public static readonly see: TSDocTagDefinition = StandardTags._defineTag({ + tagName: '@see', + synonyms: ['@seeAlso'], + syntaxKind: TSDocTagSyntaxKind.BlockTag, + standardization: Standardization.Extended + }); + /** * (Extended) * @@ -413,6 +438,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 f11e2b9f..47d3f6db 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 cabbbe4f..4a3945c3 100644 --- a/tsdoc/src/nodes/DocComment.ts +++ b/tsdoc/src/nodes/DocComment.ts @@ -2,6 +2,7 @@ import { DocNode, DocNodeKind, IDocNodeParameters } from './DocNode'; import { DocSection } from './DocSection'; import { StandardModifierTagSet } from '../details/StandardModifierTagSet'; import { IModifierTagSetParameters } from '../details/ModifierTagSet'; +import { StandardTags } from '../details/StandardTags'; import { DocBlock } from './DocBlock'; import { DocInheritDocTag } from './DocInheritDocTag'; import { StringBuilder } from '../emitters/StringBuilder'; @@ -88,6 +89,7 @@ export class DocComment extends DocNode { */ public readonly modifierTagSet: StandardModifierTagSet; + private _seeBlocks: DocBlock[]; private _customBlocks: DocBlock[]; /** @@ -106,6 +108,7 @@ export class DocComment extends DocNode { this.returnsBlock = undefined; this.modifierTagSet = new StandardModifierTagSet({ configuration: this.configuration }); + this._seeBlocks = []; this._customBlocks = []; } @@ -114,6 +117,13 @@ export class DocComment extends DocNode { return DocNodeKind.Comment; } + /** + * The collection of all `@see` DocBlockTag 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 +131,16 @@ export class DocComment extends DocNode { return this._customBlocks; } + /** + * Append an item to the seeBlocks collection. + */ + public appendSeeBlock(block: DocBlock): void { + if (!StandardTags.see.isDefinitionOfTag(block.blockTag)) { + throw new Error("Provided block is not a @see block."); + } + this._seeBlocks.push(block); + } + /** * Append an item to the customBlocks collection. */ @@ -139,6 +159,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 7e5cbf82..0e187cc1 100644 --- a/tsdoc/src/parser/NodeParser.ts +++ b/tsdoc/src/parser/NodeParser.ts @@ -323,6 +323,8 @@ export class NodeParser { docComment.deprecatedBlock = block; } else if (StandardTags.returns.isDefinitionOfTag(block.blockTag)) { docComment.returnsBlock = block; + } else if (StandardTags.see.isDefinitionOfTag(block.blockTag)) { + docComment.appendSeeBlock(block); } else { docComment.appendCustomBlock(block); }