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

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

这个函数有一个注释，描绘了这个函数的效果。但是为了便利函数调用者阅览文档，最好运用TSDoc风格的注释：

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

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

TypeScript: 使用TSDoc来编写注释

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

TypeScript: 使用TSDoc来编写注释

已然TypeScript语言服务支撑这个约好，你就应该运用它。假如一个注释描绘了一个公有API，那么它应该是TSDoc风格的。在TypeScript的上下文中，这些注释有时被称为TSDoc。你还能够运用许多常见的约好，比如@param和@returns：

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

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

TypeScript: 使用TSDoc来编写注释

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

你也能够运用TSDoc与类型界说：

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

当你查看User目标的各个字段时，你会得到上下文文档：

TypeScript: 使用TSDoc来编写注释

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

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

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

TypeScript: 使用TSDoc来编写注释

尽量防止在文档中长篇大论，最好的注释是言简意赅的。

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

总结

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