JSDoc 常用标签对照表
约 521 字大约 2 分钟
2025-08-15
文档注释标签
| 普通注释 | 文档注释 |
|---|---|
// 一句话说明``/* 多行说明 */ | /** 文档说明，配合标签使用 */ |
| 给程序员看，不规范 | 可被工具识别、提取生成文档 |
| 不能自动补全 | 支持 IDE 自动提示（VSCode、WebStorm） |
| 没有结构 | 有标准标签，结构化信息清晰 |
JSDoc 常用标签对照表（适用于 JS/TS）
| 标签 | 作用 | 示例 |
|---|---|---|
@description | 描述函数、类、变量等的用途 | @description 获取用户信息 |
@param（或 @params） | 描述函数参数及类型（推荐用 @param） | @param {string} name 用户名 |
@returns / @return | 描述函数返回值及类型 | @returns {boolean} 是否成功 |
@interface | 描述一个接口（interface）结构 | @interface User |
@typedef | 定义一个类型别名 | @typedef {Object} Config |
@property | 用于接口/对象的字段说明 | @property {string} title 标题 |
@example | 提供使用示例 | @example \n getUser("Tom") |
@deprecated | 标记该函数/变量已废弃 | @deprecated 请使用 getUserById |
@throws | 抛出的异常类型及说明 | @throws {Error} 参数错误 |
@see | 引用相关函数/文档 | @see getUserById |
@author | 说明作者信息 | @author Yumeng |
@version | 版本号 | @version 1.0.0 |
@since | 说明该功能从哪个版本开始提供 | @since 2.0.0 |
@async | 表示这是一个异步函数（async function） | @async |
文档中的 $ 和 #
$ 和 # 是命令行里的提示符（prompt），表示你是在什么身份下输入命令， 不是命令本身，也不是命令的一部分。
$ 通常表示普通用户的命令行提示符，
# 通常表示管理员（root 用户）的命令行提示符。
文档里加 $ 或 # 是为了告诉读者“这是命令行里输入的命令”， 而不是命令的输出。
复制命令时，千万不要复制这些符号，只复制后面的命令内容。
$ ls -l
# apt update代表“普通用户输入了 ls -l”
代表“管理员输入了 apt update”
# 在脚本里是注释符号，但在命令行提示符里是管理员身份的标志，两个概念不冲突。