jsdoc

JSDoc

概述

JSDoc 是 JavaScript 的文档生成器。你可以直接在代码上方编写文档注释，JSDoc 会解析这些注释并生成 API 文档。

核心原则：清晰地记录公共 API，并让注释与代码放在一起，以便文档随实现变化而保持准确。

---

注释规则

• JSDoc 注释块必须以 /** 开头（斜杠后恰好有两个星号）。
• 以 /*、/*** 或更多星号开头的注释块会被 JSDoc 解析器忽略。
• 将注释放在所记录的符号（函数、类、方法、模块等）正前方。
• 优先记录公共且可复用的 API。

---

快速入门

/**
 * Adds two numbers.
 * @param {number} a - First number.
 * @param {number} b - Second number.
 * @returns {number} Sum of the two numbers.
 */
function add(a, b) {
  return a + b;
}

---

核心标签

标签	用途
@param {Type} name - description	记录函数参数
@returns {Type} description	记录返回值
@constructor	将函数标记为构造函数
@todo text	跟踪文档中的待办任务

根据项目需要使用其他标签（例如 @example、@throws、@deprecated、@see 等）。

---

常见文档编写模式

函数

/**
 * Formats a user's full name.
 * @param {string} firstName - User first name.
 * @param {string} lastName - User last name.
 * @returns {string} The formatted full name.
 */
function formatName(firstName, lastName) {
  return `${firstName} ${lastName}`;
}

构造函数风格的函数

/**
 * Represents a book.
 * @constructor
 * @param {string} title - Book title.
 * @param {string} author - Book author.
 */
function Book(title, author) {
  this.title = title;
  this.author = author;
}

TODO 注释

/**
 * @todo Implement pagination support.
 * @todo Add validation for empty input.
 */
function listItems() {}

---

生成文档

基本命令行用法：

jsdoc book.js

默认情况下，这会在 out/ 目录中生成 HTML 文档。

你也可以传入多个源文件：

/path/to/jsdoc src/a.js src/b.js

你可以提供配置文件来设置命令行选项和自定义模板。

---

最佳实践

• 保持描述简短、具体，并聚焦于行为。
• 以一致的方式记录参数和返回值类型。
• 对需要跟踪的已知缺漏使用 @todo。
• API 签名发生变化时，更新注释。
• 优先记录导出的／公共模块，然后按需记录内部辅助项。
• 确保示例可执行且贴近实际。

---

常见错误

• 使用 /* ... */ 而不是 /** ... */ 作为 JSDoc 注释块。
• 注释与其描述的符号相距过远。
• 遗漏函数输入对应的 @param 条目。
• 描述实现细节，而不是 API 行为。
• 重构后未更新注释，导致注释与当前代码不一致。

---

其他资源

• reference.md — JSDoc 官方文档链接，便于快速查阅。
• 官方文档：https://jsdoc.app