JSDoc 3 是一個用于 JavaScript 的API文檔生成器，類似于 Javadoc 或 phpDocumentor。可以將文檔注釋直接添加到源代碼中。JSDoc 工具將掃描您的源代碼并為您生成一個 HTML 文檔網(wǎng)站。

JSDoc 速通手冊
——編程獅（w3cschool.cn）為前端新手量身打造的“一行一用”速查表

看完就能寫注釋，寫完就能出文檔！

1 起手式：一條萬能模板

/**
 * @file  文件描述
 * @author 編程獅 <dev@w3cschool.cn>
 * @license MIT
 * @since   2025-08-06
 * @version 1.0.0
 */

2 常用標簽「一行一用」

3 完整函數(shù)示例（復制即用）

/**
 * 獲取用戶詳情
 * @func
 * @param {string} id - 用戶ID
 * @param {object} [options] - 可選配置
 * @param {boolean} [options.cache=true] - 是否緩存
 * @returns {Promise<User>} 用戶實例
 * @throws {Error} 當網(wǎng)絡異常
 * @example
 * getUser('123').then(console.log);
 */
async function getUser(id, { cache = true } = {}) {
  if (!id) throw new Error('id 不能為空');
  return fetch(`/api/user/${id}?cache=${cache}`).then(r => r.json());
}

4 一鍵生成文檔

1. 安裝

   npm i -D jsdoc

2. 配置 jsdoc.json

   {
    "source": { "include": ["src"] },
    "opts": { "destination": "docs" }
   }

3. 運行

   npx jsdoc -c jsdoc.json

4. 打開 docs/index.html 查看效果。

5 速背口訣

“變量加 @type，函數(shù)加 @param，返回加 @returns，枚舉用 @enum，棄用 @deprecated 別忘寫！”

6 JSDoc 3 全部標簽速查表（共 70+）

按使用頻率分 4 級：

??? 必背（藍框）??? 常用（綠框）?? 進階（灰框）?? 其他（了解）

① 文件級

② 類型與變量

③ 函數(shù) / 方法

④ 類 / 模塊 / 命名空間

⑤ 成員可見性

⑥ 事件與監(jiān)聽

⑦ 其他實用標簽

⑧ 模板與泛型

⑨ 完整模板速用

/**
 * @file 用戶模塊
 * @author 編程獅 <dev@w3cschool.cn>
 * @since 1.0.0
 */


/**
 * @typedef {Object} User
 * @property {string} name  用戶名
 * @property {number} age   年齡
 */


/**
 * 創(chuàng)建用戶
 * @func
 * @param {User} user
 * @returns {Promise<User>}
 * @throws {Error} 參數(shù)非法
 * @example
 * createUser({name:'Tom',age:18})
 */
async function createUser(user) { ... }