TypeScript: 使用TSDoc来编写注释

下面是一个用TypeScript来生成问候语函数：

// 生成一个问候语，结果是格式化显示的
function greet(title: string, name: string) {
    return `Hello ${title} ${name}`;
}

这个函数有一个注释，描述了这个函数的作用。但是为了方便函数调用者阅读文档，最好使用TSDoc风格的注释：

/** 生成一个问候语，结果是格式化显示的 */
function greetTSDoc(title: string, name: string) {
    return `Hello ${title} ${name}`;
}

原因是，在各种编辑器中几乎都有一个通用的惯例，当函数被调用时，会出现TSDoc风格的注释：

而内联注释则没有这样的处理：

既然TypeScript语言服务支持这个约定，你就应该使用它。如果一个注释描述了一个公有API，那么它应该是TSDoc风格的。在TypeScript的上下文中，这些注释有时被称为TSDoc。你还可以使用许多常见的约定，比如@param和@returns：

/**
* 生成一个问候语
* @param title 称谓
* @param name 名字
* @returns 一种格式化的问候语，供人使用
*/
function greetFullTSDoc(name: string, title: string) {
    return `Hello ${title}, ${name}`;
}

这样可以使编辑器在你写出的函数调用时显示每个参数的相关文档：

一个@param标注可以让你的编辑器在你键入当前参数时显示它的文档.

你也可以使用TSDoc与类型定义：

/** 用户信息 */
interface User {
    /** 名字 */
    name: string;
    /** 年龄 */
    age: number;
    /** 性别 */
    gender: string;
}

当你检查User对象的各个字段时，你会得到上下文文档：

如上图，当你在编辑器中把鼠标放在一个字段时，就会显示字段的TSDoc文档。

TSDoc注释是使用Markdown进行格式化的，所以如果你想使用粗体、斜体或者项目列表，你可以这样做：

/**
* this _interface_ has **three** properties：
* 1. x
* 2. y
* 3. z
*/
export interface Vector3D {
    x: number;
    y: number;
    z: number;
}

尽量避免在文档中长篇大论，最好的注释是短小精悍的。

JSDoc包含了一些用于指定类型信息的约定(@param {string} name ...),但应该避免这些约定，而使用TypeScript类型。

总结

• 使用TSDoc风格的注释来导出的函数、类和类型生成文档。这有助于编辑器在遇到相关内容时为使用者显示信息。
• 使用@param、@returns和Markdown进行格式化。