- TSDoc：注释规范
TSDoc 是一个标准化 TypeScript 代码中使用的文档注释的建议，以便不同的工具可以提取内容而不会被彼此的标记混淆。
1.1 注释标记简表
注释
描述
@alpha
指定 API 项的发布阶段为“alpha”。它旨在用于 第三方开发者最终，但尚未发布。该工具可能会从 公开发布。
@beta
指定 API 项的发布阶段为“测试版”。它已通过实验性发布给第三方开发人员 为了收集反馈。
@decorator
ECMAScript 装饰器有时是一个重要的部分 的 API 协定。但是，今天TypeScript编译器不代表.d.ts输出文件中的装饰器 由 API 使用者使用。该标记提供了一种解决方法，允许将装饰器表达式括起来 在文档评论中。
@deprecated
此块标记表示不再支持 API 项，并且可能会在将来的版本中删除。 标记后跟一个描述推荐替代方案的句子。它递归应用 容器的成员。例如，如果一个类被弃用，那么它的所有成员也是如此。
@defaultValue
如果未显式分配值，则此块标记用于记录字段或属性的默认值。此标记只能与属于 TypeScript class 或 interface 成员的字段或属性一起使用。
@eventProperty
当应用于类或接口属性时，这表示该属性 返回事件处理程序可以附加到的事件对象。事件处理 API 是实现定义的，但通常属性返回类型是一个类 与成员如 addHandler() 和 removeHandler()。文档工具可以 在“Events”标题下显示此类属性，而不是通常的“Properties”标题。
@example
指示应作为示例演示如何使用 API 的文档部分。 它可能包括代码示例。
@experimental
与 @beta 相同的语义，但由不支持@alpha发布阶段的工具使用。
@inheritDoc
此内联标记用于通过从另一个 API 项复制 API 项的文档来自动生成该文档 接口项。内联标记参数包含对其他项的引用，该项可能是不相关的类， 甚至是从单独的 NPM 包导入。
@internal
指定不计划由第三方开发人员使用 API 项。该工具可能会修剪 公开发布的声明。在某些实现中，可能允许某些指定的包 使用内部 API 项，例如，因为包是同一产品的组件。
@label
内联 {@label} 标记用于标记声明，以便可以使用 TSDoc 声明引用表示法。
@link
{@link} 内联标记用于创建指向文档系统中其他页面或通用internet URLs的超链接。特别是，它支持引用API项的表达式。
@override
这个修饰符的语义类似于C#或Java中的override关键字。对于成员函数或属性，显式指示此定义重写(即重新定义)从基类继承的定义。基类定义通常会被标记为虚拟的。
@packageDocumentation
用于表示描述整个NPM包的文档注释(相对于属于该包的单个API项)。@packageDocumentation 注释位于 .d.ts 文件中，该文件充当包的入口点，它应该是在该文件中遇到的第一个/** 注释。包含 @packageDocumentation标签的注释不应该用于描述单个API项。
@param
用于记录函数参数。@param 标记后面是参数名，后面是连字符，再后面是描述。
@privateRemarks
启动不面向公众的其他文档内容的一部分。 工具必须从 API 参考网站（生成的 .d.ts 文件）中省略整个部分， 以及包含内容的任何其他输出。
@public
指定 API 项的发布阶段为 “public”。已经正式发布给第三方开发者， 并且其签名保证稳定（例如，遵循语义版本控制规则）。
@readonly
此修饰符标记指示API项应该被记录为只读的，即使TypeScript类型系统可能另有指示。例如，假设一个类属性有一个setter函数，它总是抛出一个异常，说明该属性不能赋值；在这种情况下，可以添加 @readonly 修饰符，以便该属性在文档中显示为只读。
@remarks
API项目的主要文件被分成一个简短的“总结”部分，随后是一个更详细的“备注”部分。在文档网站上，索引页(例如显示类的成员)将只显示简短的摘要，而详细页(例如描述单个成员)将显示摘要，后跟备注。@remarks 块标记结束摘要部分，并开始文档注释的备注部分。
@returns
用于记录函数的返回值。
@sealed
这个修饰符的语义类似于C#或Java中的 sealed 关键字。对于类，指示子类不能从类继承。对于成员函数或属性，表示子类不能覆盖(即重定义)成员。
@see
用于生成对可能与 当前项目。
@throws
用于记录可能由函数或属性引发的异常类型。
@typeParam
用于记录通用参数。@typeParam 标记后面是参数名、连字符和说明。TSDoc解析器识别这种语法，并将它提取到DocParamBlock节点中。
@virtual
这个修饰符的语义类似于C#或Java中的 virtual 关键字。对于成员函数或属性，显式指示子类可以重写(即重定义)成员。
1.2 标记用法详解
本节整理和翻译自 TSDoc 规范官网
1.2.1 @alpha
指定 API 项的发布阶段为“alpha”。它旨在用于 第三方开发者最终，但尚未发布。该工具可能会从 公开发布。
例如：
/**- Represents a book in the catalog.
- @public
/
export class Book {
/* - The title of the book.
- @alpha
/
public get title(): string;
/* - The author of the book.
/
public get author(): string;
};
在这个例子中，Book.author从包含它的类继承了它的@public名称，而Book.title被标记为“alpha”。
1.2.2 @beta
指定 API 项的发布阶段为“测试版”。它已通过实验性发布给第三方开发人员 为了收集反馈。
例如：
/* - Represents a book in the catalog.
- @public
/
export class Book {
/* - The title of the book.
- @beta
/
public get title(): string;
/* - The author of the book.
/
public get author(): string;
};
在这个例子中，Book.author从包含它的类继承了它的@public名称，而Book.title被标记为“beta”。
1.2.3 @decorator
ECMAScript装饰器 有时是API契约的重要组成部分。然而，今天TypeScript编译器并不表示API消费者使用的. d.ts输出文件中的装饰器。@decorator标签提供了一种变通方法，允许在doc注释中引用decorator表达式。
例如：
class Book {
/* - The title of the book.
- @decorator
@jsonSerialized - @decorator
@jsonFormat(JsonFormats.Url)
/
@jsonSerialized
@jsonFormat(JsonFormats.Url)
public website: string;
}
1.2.4 @deprecated
此块标记表示不再支持 API 项，并且可能会在将来的版本中删除。 标记后跟一个描述推荐替代方案的句子。它递归应用 容器的成员。例如，如果一个类被弃用，那么它的所有成员也是如此。
例如：
/* - The base class for controls that can be rendered.
* - @deprecated Use the new {@link Control} base class instead.
/
export class VisualControl {
. . .
}
1.2.5 @defaultValue
如果未显式分配值，则此块标记用于记录字段或属性的默认值。此标记只能与属于 TypeScript class 或 interface 成员的字段或属性一起使用。
例如：
enum WarningStyle {
DialogBox,
StatusMessage,
LogOnly
}
interface IWarningOptions {
/* - Determines how the warning will be displayed.
* - @remarks
- See {@link WarningStyle| the WarningStyle enum} for more details.
* - @defaultValue
WarningStyle.DialogBox
/
warningStyle: WarningStyle;
/* - Whether the warning can interrupt a user's current activity.
- @defaultValue
- The default is
trueunless WarningStyle.StatusMessagewas requested.
/
cancellable?: boolean;
/*- The warning message
/
message: string;
}
1.2.6 @eventProperty
当应用于类或接口属性时，这表示该属性 返回事件处理程序可以附加到的事件对象。事件处理 API 是实现定义的，但通常属性返回类型是一个类 与成员如 addHandler() 和 removeHandler()。文档工具可以 在“Events”标题下显示此类属性，而不是通常的“Properties”标题。
例如：
class MyClass {
/*- This event is fired whenever the application navigates to a new page.
- @eventProperty
/
public readonly navigatedEvent: FrameworkEvent;
}
1.2.7 @example
指示应作为示例演示如何使用 API 的文档部分。 它可能包括代码示例。
例如：
/*
- Adds two numbers together.
- @example
- Here's a simple example:
- ```
- // Prints "2":
- console.log(add(1,1));
- ```
- @example
- Here's an example with negative numbers:
- ```
- // Prints "0":
- console.log(add(1,-1));
- ```
/
export function add(x: number, y: number): number {
}
例如：
/* - Parses a JSON file.
* - @param path - Full path to the file.
- @returns An object containing the JSON data.
* - @example Parsing a basic JSON file
* Contents of
file.json- ```json
- {
- "exampleItem": "text"
- }
- ```
* Usage
- ```ts
- const result = parseFile("file.json");
- ```
* Result
- ```ts
- {
- exampleItem: 'text',
- }
- ```
/
1.2.8 @experimental
例如：
/* - Represents a book in the catalog.
- @public
/
export class Book {
/* - The title of the book.
- @experimental
/
public get title(): string;
/* - The author of the book.
/
public get author(): string;
};
在这个例子中，Book.author从包含它的类继承了它的@public名称，而Book.title被标记为“experimental”。
1.2.9 @inheritDoc
这个内联标签用于通过从另一个API项复制来自动生成一个API项的文档。inline tag参数包含对另一个项目的引用，它可能是一个不相关的类，甚至是从一个单独的NPM包导入的。
注意:声明引用的符号尚未最终确定。
什么被复制
@inheritDoc 标记不会复制整个注释体。仅复制以下组件:
• 摘要部分
• @remarks块
• @params块
• @typeParam块
• @returns块
其他标签(如 @defaultValue 或 @example )不会被复制，需要显式包含在 @inheritDoc 标签之后。当指定了@inheritDoc标记时，不能在注释中指定summary部分和 @remarks 部分。
例如：
import { Serializer } from 'example-library';
/* - An interface describing a widget.
- @public
/
export interface IWidget {
/* - Draws the widget on the display surface.
- @param x - the X position of the widget
- @param y - the Y position of the widget
/
public draw(x: number, y: number): void;
}
/** @public /
export class Button implements IWidget {
/ {@inheritDoc IWidget.draw} */
public draw(x: number, y: number): void {
. . .
}
/ - {@inheritDoc example-library#Serializer.writeFile}
- @deprecated Use {@link example-library#Serializer.writeFile} instead.
/
public save(): void {
. . .
}
}
1.2.10 @internal
指定不计划由第三方开发人员使用 API 项。该工具可能会修剪 公开发布的声明。在某些实现中，可能允许某些指定的包 使用内部 API 项，例如，因为包是同一产品的组件。
例如：
/* - Represents a book in the catalog.
- @public
/
export class Book {
/* - The title of the book.
- @internal
/
public get _title(): string;
/* - The author of the book.
/
public get author(): string;
};
1.2.11 @label
内联 {@label} 标记用于标记声明，以便可以使用 TSDoc 声明引用表示法。
{@label}符号尚未最终确定。
例如：
export interface Interface {
/* - Shortest name: {@link InterfaceL1.(:STRING_INDEXER)}
- Full name: {@link (InterfaceL1:interface).(:STRING_INDEXER)}
* - {@label STRING_INDEXER}
*/
/**
- Shortest name: {@link InterfaceL1.(:NUMBER_INDEXER)}
- Full name: {@link (InterfaceL1:interface).(:NUMBER_INDEXER)}
* - {@label NUMBER_INDEXER}
*/
/**
- Shortest name: {@link InterfaceL1.(:FUNCTOR)}
- Full name: {@link (InterfaceL1:interface).(:FUNCTOR)}
* - {@label FUNCTOR}
/
(source: string, subString: string): boolean;
/* - Shortest name: {@link InterfaceL1.(:CONSTRUCTOR)}
- Full name: {@link (InterfaceL1:interface).(:CONSTRUCTOR)}
* - {@label CONSTRUCTOR}
/
new (hour: number, minute: number);
}
1.2.12 @link
{@link} 内联标记用于创建指向文档系统中其他页面或通用internet URLs的超链接。特别是，它支持引用API项的表达式。
声明引用的符号尚未最终确定。
例如：
/*- Let's learn about the
{@link}tag.
* - @remarks
* - Links can point to a URL: {@link https://github.com/microsoft/tsdoc}
* - Links can point to an API item: {@link Button}
* - You can optionally include custom link text: {@link Button | the Button class}
* - Suppose the
Buttonclass is part of an external package. In that case, we - can include the package name when referring to it:
* - {@link my-control-library#Button | the Button class}
* - The package name can include an NPM scope and import path:
* - {@link @microsoft/my-control-library/lib/Button#Button | the Button class}
* - The TSDoc standard calls this notation a "declaration reference". The notation supports
- references to many different kinds of TypeScript declarations. This notation was originally
- designed for use in
{@link}and{@inheritDoc}tags, but you can also use it in your - own custom tags.
* - For example, the
Buttoncan be part of a TypeScript namespace:
* - {@link my-control-library#controls.Button | the Button class}
* - We can refer to a member of the class:
* - {@link controls.Button.render | the render() method}
* - If a static and instance member have the same name, we can use a selector to distinguish them:
* - {@link controls.Button.(render:instance) | the render() method}
* - {@link controls.Button.(render:static) | the render() static member}
* - This is also how we refer to the class's constructor:
* - {@link controls.(Button:constructor) | the class constructor}
* - Sometimes a name has special characters that are not a legal TypeScript identifier:
* - {@link restProtocol.IServerResponse."first-name" | the first name property}
* - Here is a fairly elaborate example where the function name is an ECMAScript 6 symbol,
- and it's an overloaded function that uses a label selector (defined using the
{@label} - TSDoc tag):
* - {@link my-control-library#Button.([UISymbols.toNumberPrimitive]:OVERLOAD_1)
- | the toNumberPrimitive() static member}
* - See the TSDoc spec for more details about the "declaration reference" notation.
/
1.2.13 @override
这个修饰符的语义类似于C#或Java中的override关键字。对于成员函数或属性，显式指示此定义重写(即重新定义)从基类继承的定义。基类定义通常会被标记为虚拟的。
文档工具可以强制一致地应用@virtual、@override和/或@sealed修饰符，但是这不是TSDoc标准所要求的。
例如：
class Base {
/** @virtual /
public render(): void {
}
/ @sealed */
public initialize(): void {
}
}
class Child extends Base {
/ @override /
public render(): void;
}
1.2.14 @packageDocumentation
用于表示描述整个NPM包的文档注释(相对于属于该包的单个API项)。@packageDocumentation 注释位于.d.ts文件中，该文件充当包的入口点，它应该是在该文件中遇到的第一个 / 注释。包含 @packageDocumentation 标签的注释不应该用于描述单个API项。
例如：
// Copyright (c) Example Company. All rights reserved. Licensed under the MIT license.
/ - A library for building widgets.
* - @remarks
- The
widget-libdefines the {@link IWidget} interface and {@link Widget} class, - which are used to build widgets.
* - @packageDocumentation
/
/* - Interface implemented by all widgets.
- @public
/
export interface IWidget {
/*
- Let's learn about the
- Draws the widget on the screen.
/
render(): void;
}
1.2.15 @param
用于记录函数参数。@param 标记后面是参数名，后面是连字符，再后面是描述。
例如：
/*- Returns the average of two numbers.
* - @remarks
- This method is part of the {@link core-library#Statistics | Statistics subsystem}.
* - @param x - The first input number
- @param y - The second input number
- @returns The arithmetic mean of
xandy
* - @beta
/
function getAverage(x: number, y: number): number {
return (x + y) / 2.0;
}
1.2.16 @privateRemarks
启动不面向公众的其他文档内容的一部分。 工具必须从 API 参考网站（生成的 .d.ts 文件）中省略整个部分， 以及包含内容的任何其他输出。
例如：
/** - The summary section should be brief. On a documentation web site,
- it will be shown on a page that lists summaries for many different
- API items. On a detail page for a single item, the summary will be
- shown followed by the remarks section (if any).
* - @remarks
* - The main documentation for an API item is separated into a brief
- "summary" section optionally followed by an
@remarksblock containing - additional details.
* - @privateRemarks
* - The
@privateRemarkstag starts a block of additional commentary that is not meant - for an external audience. A documentation tool must omit this content from an
- API reference web site. It should also be omitted when generating a normalized
- .d.ts file. /
1.2.17 @public
指定 API 项的发布阶段为“public”。已经正式发布给第三方开发者， 并且其签名保证稳定（例如，遵循语义版本控制规则）。
例如：
/** - Represents a book in the catalog.
- @public
/
export class Book {
/*
- Returns the average of two numbers.
- The title of the book.
- @internal
/
public get _title(): string;
/* - The author of the book.
/
public get author(): string;
};
1.2.18 @readonly
此修饰符标记指示 API 项应记录为只读，即使 TypeScript 类型系统可能另有指示。例如，假设一个类属性有一个 setter 函数，该函数始终 引发异常，说明无法分配属性;在这种情况下，@readonly 修饰符 可以添加，以便属性在文档中显示为只读。
例如：
export class Book {
/* - Technically property has a setter, but for documentation purposes it should
- be presented as readonly.
- @readonly
/
public get title(): string {
return this._title;
}
public set title(value: string) {
throw new Error('This property is read-only!');
}
}
1.2.19 @remarks
API项目的主要文件被分成一个简短的“总结”部分，随后是一个更详细的“备注”部分。在文档网站上，索引页(例如显示类的成员)将只显示简短的摘要，而详细页(例如描述单个成员)将显示摘要，后跟备注。@remarks 块标记结束摘要部分，并开始文档注释的备注部分。
例如：
//代码效果参考：https://www.xx-ph.com/sitemap/post.html
/*- The summary section should be brief. On a documentation web site,
- it will be shown on a page that lists summaries for many different
- API items. On a detail page for a single item, the summary will be
- shown followed by the remarks section (if any).
* - @remarks
* - The main documentation for an API item is separated into a brief
- "summary" section optionally followed by an
@remarksblock containing - additional details.
* - @privateRemarks
* - The
@privateRemarkstag starts a block of additional commentary that is not meant - for an external audience. A documentation tool must omit this content from an
- API reference web site. It should also be omitted when generating a normalized
- .d.ts file. /
