Item 68: Use TSDoc for API Comments
要点
- 使用 JSDoc/TSDoc 格式的注释来记录导出的函数、类和类型。这有助于编辑器在最相关时为用户提供信息。
- 使用
@param
、@returns
和 Markdown 来进行格式化。 - 避免在文档中包含类型信息(参见第 31 条)。
- 使用
@deprecated
标记已废弃的 API。
正文
下面是一个用于生成问候语的 TypeScript 函数:
// Generate a greeting. Result is formatted for display.
function greet(name: string, title: string) {
return `Hello ${title} ${name}`
}
作者贴心地为这个函数写了注释,描述了它的作用。但如果你希望为函数的使用者编写文档,最好使用 JSDoc 风格的注释:
/** Generate a greeting. Result is formatted for display. */
function greetJSDoc(name: string, title: string) {
return `Hello ${title} ${name}`
}
原因在于,几乎所有编辑器都会在调用函数时显示 JSDoc 风格的注释(见下图 8-1)。
相比之下,内联注释则不会被这样处理(见下图 8-2)。
TypeScript 语言服务支持这种约定,你应该充分利用它。如果注释描述的是公共 API,就应该使用 JSDoc。在 TypeScript 语境下,这类注释有时也被称为 TSDoc。你可以使用许多常见的标签,比如 @param 和 @returns:
/**
* Generate a greeting.
* @param name Name of the person to greet
* @param title The person's title
* @returns A greeting formatted for human consumption.
*/
function greetFullTSDoc(name: string, title: string) {
return `Hello ${title} ${name}`
}
这样,编辑器在你编写函数调用时会显示每个参数的相关文档(如图 8-3 所示)。这里仅显示了 name 参数的文档,而不是 title。
你也可以在类型定义中使用 TSDoc:
/** A measurement performed at a time and place. */
interface Measurement {
/** Where was the measurement made? */
position: Vector3D
/** When was the measurement made? In seconds since epoch. */
time: number
/** Observed momentum */
momentum: Vector3D
}
当你查看 Measurement 对象的各个字段时,会获得上下文相关的文档(见图 8-4)。
只要类型是"同态"的(参见第 15 项),字段上的文档就会通过映射类型(如 Partial 和 Pick 等辅助类型)被保留下来。
你可以用 @template 标签为泛型类型的类型参数编写文档。第 50 项会详细介绍其用法。
TSDoc 注释支持 Markdown 格式,因此你可以使用粗体、斜体或项目符号列表等格式(见图 8-5)。
不过,尽量避免在文档中写"长篇大论"。最好的注释应简明扼要、直击要点。
JSDoc 包含一些用于指定类型信息的约定(如 @param {string} name ...),但你应避免这样做,而应优先使用 TypeScript 类型(参见第 31 项)。
最后,你应使用 @deprecated 标签标记已废弃的符号。这不仅能清楚地表明某个函数已废弃,还能启用 TSDoc 最强大的特性之一:被 @deprecated 标记的符号通常会以删除线形式显示。这样你甚至无需查看符号详情就能知道它已废弃,如图 8-6 所示。
如果你标记了某个方法为废弃,请务必告知用户新的替代方案。至少应在文档中给出相关参考。
要点回顾
- 使用 JSDoc/TSDoc 格式的注释来记录导出的函数、类和类型。这有助于编辑器在最相关时为用户提供信息。
- 使用
@param
、@returns
和 Markdown 来进行格式化。 - 避免在文档中包含类型信息(参见第 31 条)。
- 使用
@deprecated
标记已废弃的 API。