JSDoc 3 是一个用于 JavaScript 的API文档生成器,类似于 Javadoc 或 phpDocumentor。可以将文档注释直接添加到源代码中。JSDoc 工具将扫描您的源代码并为您生成一个 HTML 文档网站。
JSDoc 速通手册
——编程狮(w3cschool.cn)为前端新手量身打造的“一行一用”速查表
看完就能写注释,写完就能出文档!
1 起手式:一条万能模板
/**
* @file 文件描述
* @author 编程狮 <dev@w3cschool.cn>
* @license MIT
* @since 2025-08-06
* @version 1.0.0
*/
2 常用标签「一行一用」
| 场景 | 简写模板 | 备注 |
|---|---|---|
| 描述变量 | /** @type {number} */ let count |
写类型即可 |
| 描述函数 | /** @param {string} name - 用户名 */ |
必传参数 |
| 可选参数 | /** @param {number} [age=18] - 年龄 */ |
中括号 + 默认值 |
| 多个类型 | /** @type {(string\|number)} id */ |
管道符 |
| 对象结构 | /** @type {{a: string, b: number}} */ |
行内对象 |
| 返回类型 | /** @returns {Promise<boolean>} */ |
Promise 也支持 |
| 回调函数 | /** @callback FetchCb @param {string} url @returns {Promise} */ |
先定义后使用 |
| 枚举 | /** @enum {number} */ const STATUS = { OK: 200, ERROR: 500 } |
自动生成枚举文档 |
| 类注释 | /** @class User @desc 用户实体 */ |
构造函数上加 |
| 弃用 | /** @deprecated 用 fetchDataAsync 代替 */ |
IDE 会画删除线 |
3 完整函数示例(复制即用)
/**
* 获取用户详情
* @func
* @param {string} id - 用户ID
* @param {object} [options] - 可选配置
* @param {boolean} [options.cache=true] - 是否缓存
* @returns {Promise<User>} 用户实例
* @throws {Error} 当网络异常
* @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 一键生成文档
- 安装
npm i -D jsdoc - 配置
jsdoc.json{ "source": { "include": ["src"] }, "opts": { "destination": "docs" } } - 运行
npx jsdoc -c jsdoc.json - 打开
docs/index.html查看效果。
5 速背口诀
“变量加
@type,函数加@param,返回加@returns,枚举用@enum,弃用@deprecated别忘写!”
6 JSDoc 3 全部标签速查表(共 70+)
按使用频率分 4 级:
⭐⭐⭐ 必背(蓝框) ⭐⭐ 常用(绿框) ⭐ 进阶(灰框) ◦ 其他(了解)
① 文件级
| 标签 | 说明 | 示例 |
|---|---|---|
@file / @fileoverview |
文件描述 | @file 用户模块入口 |
@author |
作者 | @author 编程狮 <dev@w3cschool.cn> |
@copyright |
版权 | @copyright 2025 w3cschool |
@license |
许可证 | @license MIT |
@version |
版本 | @version 1.2.0 |
@since |
起始版本 | @since 2025-08-06 |
② 类型与变量
| 标签 | 说明 | 示例 |
|---|---|---|
@type ⭐⭐⭐ |
变量/返回值类型 | @type {number} |
@typedef ⭐⭐ |
自定义类型 | @typedef {{x:number,y:number}} Point |
@callback ⭐⭐ |
回调类型 | @callback FetchCb |
@enum ⭐ |
枚举 | @enum {number} STATUS |
@var ◦ |
变量别名 | @var {string} title |
@constant / @const ⭐⭐ |
常量 | @constant {string} API_ROOT |
@readonly ⭐ |
只读 | @readonly |
@default ⭐ |
默认值 | @default 42 |
③ 函数 / 方法
| 标签 | 说明 | 示例 |
|---|---|---|
@param / @arg ⭐⭐⭐ |
参数 | @param {string} name - 用户名 |
@returns / @return ⭐⭐⭐ |
返回值 | @returns {Promise<User>} |
@throws / @exception ⭐⭐ |
抛出异常 | @throws {Error} 参数错误 |
@example ⭐⭐ |
用法示例 | @example add(1,2) // 3 |
@async ⭐ |
异步 | @async |
@generator / @yields ◦ |
生成器 | @yields {number} |
@this ◦ |
this 指向 | @this {HTMLElement} |
④ 类 / 模块 / 命名空间
| 标签 | 说明 | 示例 |
|---|---|---|
@class / @constructor ⭐⭐⭐ |
构造函数 | @class Person |
@classdesc ⭐ |
类描述 | @classdesc 用户实体 |
@extends / @augments ⭐⭐ |
继承 | @extends Animal |
@implements ⭐ |
实现接口 | @implements Drawable |
@interface ⭐ |
接口 | @interface EventEmitter |
@abstract / @virtual ◦ |
抽象 | @abstract draw() |
@override ⭐ |
重写 | @override |
@static ⭐ |
静态成员 | @static findById() |
@instance ◦ |
实例成员 | @instance |
@inner ◦ |
内部成员 | @inner toString |
@memberof ⭐ |
隶属对象 | @memberof utils |
@namespace ⭐⭐ |
命名空间 | @namespace math |
@module ⭐⭐ |
模块 | @module user/api |
@exports ⭐ |
出口 | @exports UserModel |
@requires ⭐ |
依赖模块 | @requires lodash |
⑤ 成员可见性
| 标签 | 说明 |
|---|---|
@public ⭐ |
公开(默认) |
@private ⭐⭐ |
私有 |
@protected ⭐⭐ |
受保护 |
@package ◦ |
包内可见 |
⑥ 事件与监听
| 标签 | 说明 |
|---|---|
@event ⭐ |
定义事件 |
@listens ◦ |
监听事件 |
@fires / @emits ◦ |
触发事件 |
⑦ 其他实用标签
| 标签 | 说明 |
|---|---|
@description / @desc ⭐⭐ |
长描述 |
@summary ⭐ |
简短描述 |
@deprecated ⭐⭐ |
已弃用 |
@see ⭐ |
参考链接 |
@link / @linkcode / @linkplain ⭐ |
内联链接 {@link URL} |
@tutorial ◦ |
教程链接 |
@ignore ◦ |
忽略该符号 |
@todo ⭐ |
TODO 任务 |
@borrows ◦ |
借用其他注释 |
@name ◦ |
强制名称(用于虚拟注释) |
@variation ◦ |
同名变体 |
@external ◦ |
外部类型 |
@mixin / @mixes ⭐ |
混入 |
⑧ 模板与泛型
| 标签 | 说明 |
|---|---|
@template ⭐ |
泛型参数 @template T |
@satisfies ◦ |
TypeScript 专用 |
⑨ 完整模板速用
/**
* @file 用户模块
* @author 编程狮 <dev@w3cschool.cn>
* @since 1.0.0
*/
/**
* @typedef {Object} User
* @property {string} name 用户名
* @property {number} age 年龄
*/
/**
* 创建用户
* @func
* @param {User} user
* @returns {Promise<User>}
* @throws {Error} 参数非法
* @example
* createUser({name:'Tom',age:18})
*/
async function createUser(user) { ... }
小狮博客