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 b6bb5f62..727ce318 100644 --- a/tsdoc/src/nodes/DocComment.ts +++ b/tsdoc/src/nodes/DocComment.ts @@ -5,6 +5,8 @@ import { DocBlock } from './DocBlock'; import { DocInheritDocTag } from './DocInheritDocTag'; import { StringBuilder } from '../emitters/StringBuilder'; import { DocParamCollection } from './DocParamCollection'; +import { IModifierTagSetParameters } from '../details/ModifierTagSet'; +import { StandardTags } from '../details/StandardTags'; /** * Constructor parameters for {@link DocComment}. @@ -87,6 +89,7 @@ export class DocComment extends DocNode { */ public readonly modifierTagSet: StandardModifierTagSet; + private _seeBlocks: DocBlock[]; private _customBlocks: DocBlock[]; /** @@ -109,6 +112,7 @@ export class DocComment extends DocNode { }; this.modifierTagSet = new StandardModifierTagSet(modifierTagSetParameters); + this._seeBlocks = []; this._customBlocks = []; } @@ -117,6 +121,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. */ @@ -124,6 +135,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. */ @@ -142,6 +163,7 @@ export class DocComment extends DocNode { this.typeParams.count > 0 ? this.typeParams : undefined, this.returnsBlock, ...this.customBlocks, + ...this.seeBlocks, this.inheritDocTag, ...this.modifierTagSet.nodes ]; @@ -169,5 +191,4 @@ export class DocComment extends DocNode { } // Circular reference -import { TSDocEmitter } from '../emitters/TSDocEmitter';import { IModifierTagSetParameters } from '../details/ModifierTagSet'; - +import { TSDocEmitter } from '../emitters/TSDocEmitter'; \ No newline at end of file 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); }