JSDoc注释规范详解param、return、type等15个必会标签一次学会【免费下载链接】jsdocAn API documentation generator for JavaScript.项目地址: https://gitcode.com/gh_mirrors/js/jsdocJSDoc 是 JavaScript 开发者最常用的API 文档生成器An API documentation generator for JavaScript它通过解析源码中的/** ... */块注释自动产出结构化的 API 文档。本文带你一次学会 JSDoc 注释规范中最核心的 15 个标签——param、returns、type、class 等让你写的注释既规范又高效。一、JSDoc 是什么为什么必学JSDoc的工作流程非常简单你在函数、类、变量上方写注释 → 运行 jsdoc.js 命令行工具 → 自动生成 HTML 文档站点。它的核心优势文档与代码同处一仓注释即文档永远不会过期脱节零学习成本入门会写注释就会写 JSDocIDE 原生支持VS Code 等编辑器能读取 JSDoc 提供自动补全和类型提示️模块化架构核心标签定义在 core.js 中标签体系清晰可扩展 一句话记忆注释里用标签声明参数、返回值和类型JSDoc 就能自动生成专业文档。二、JSDoc 注释的基本格式一条 JSDoc 注释遵循固定结构以/**开头注意必须是块注释不是//第一行写一句话描述会成为文档标题空行后跟若干标签行以*/结尾/** * 按名称查找用户。 * * param {string} name 要查找的用户名 * returns {object} 匹配到的用户对象 */ function findUser(name) { /* ... */ }标签的官方定义全部集中在 packages/jsdoc-tag/lib/definitions/core.js每个标签都声明了是否必须带值、能否带类型等约束。三、15个核心标签速查手册1. param —— 声明函数参数最高频param用于描述函数的每一个参数格式为param {类型} 名称 描述/** * param {string} targetName 要查找的目标名称 * param {function} callback 回调函数 */ function find(targetName, callback) {}小贴士可选参数用方括号param [asynctrue] 是否异步执行联合类型用|param {string|number} xarg、argument都是它的别名更多变体可参考 paramtag.js2. returnsreturn—— 声明返回值returns描述函数的返回值类型和含义return是它的简写别名/** * 查找目标并返回结果列表。 * returns {string|Arraystring} 找到的目标名称 */ function find(targetName) {}参考示例returnstag.js。3. type —— 声明变量/属性的类型给变量或对象属性显式标注类型/** * type {number} 当前计数器 */ let count 0;注意type 后面只能跟类型表达式不能跟描述文字这是 core.js 中mustNotHaveDescription的硬约束。4. typedef —— 定义可复用类型复杂对象类型建议用typedef先起名之后到处引用/** typedef {string|number} calc.NumberLike */ /** param {calc.NumberLike} x 数字或字符串 */ function readNumber(x) {}这样避免了长类型表达式反复书写维护性大幅提升。实战示例见 typedeftag.js。5. class —— 标记构造函数为类/** * 描述 Ticker 类的功能。 * class */ var Ticker function() {};在函数式构造函数上标注class后JSDoc 才会把它当作类来归类展示。示例见 classtag.js。6. property —— 描述对象的属性给类或对象属性补充类型与说明/** * property {string} hostname 服务器地址 * property {number} port 端口号 */ function MySocket() {}7. example —— 提供使用示例example允许在文档中嵌入代码示例支持重复使用多次JSDoc 会自动保留其中的空白格式/** * 创建任务并执行。 * example * const task new Task(build); * task.run(); */ function Task(name) {}8. throwsexception—— 声明可能抛出的异常/** * throws {InvalidArgumentException} 参数非法时抛出 */ function foo(x) {}exception是throws的别名两者完全等价。完整示例见 exceptiontag.js。9. since —— 标注引入版本/** * since 2.0.0 */ function newFeature() {}方便使用者快速判断我用的版本是否包含这个 API。10. deprecated —— 标记废弃 API/** * deprecated 请改用 {link findUser} */ function oldFindUser() {}带值说明替代方案时效果最好——文档中会直接显示弃用提示横幅。11. author —— 标注作者可重复使用多次书写会累加成数组/** * author 张三 * author 李四 lisiexample.com */ function coreApi() {}12. see —— 关联相关文档在文档中建立延伸阅读链接/** * see {link findUser} 查找函数的文档 */ function helper() {}13. module —— 声明模块把若干导出归入同一逻辑模块/** * 用户管理模块。 * module user-manager */配合exports使用可将一组函数打包成统一的模块文档页。14. ignore —— 从文档中排除对纯内部实现、不想出现在公开文档中的代码加一行即可隐身/** ignore */ function _internalHelper() {}15. summary —— 一句话摘要在长描述之外提供独立的摘要字段方便文档目录展示/** * 完整的详细描述…… * summary 快速计算两个数的和 */ function add(a, b) {}四、一份完整的标准答案模板把常用标签组合起来就是一个生产级函数的标准注释模板/** * 根据条件查询用户列表。 * * param {string} name 用户名支持模糊匹配 * param {number} [limit10] 返回条数上限 * returns {Arrayobject} 用户对象数组 * throws {InvalidArgumentException} name 为空时抛出 * since 1.2.0 * author JSDoc Team * see {link createUser} * example * const users findUsers(zhang, 5); */ function findUsers(name, limit) {}五、新手常见错误清单 ⚠️错误正确做法用//或/* */写注释必须用/** */块注释忘记returns的类型大括号写returns {string}而非returns stringtype后加了描述文字type {object}单独一行描述写在注释第一行参数顺序与函数签名不一致param顺序应与函数形参一一对应拼写return时漏了类型return也支持带类型建议统一用returns六、下一步如何运行 JSDoc 生成文档# 安装项目依赖并运行 git clone https://gitcode.com/gh_mirrors/js/jsdoc cd jsdoc nvm install npm link jsdoc your-file.js运行后会自动输出 HTML 文档。更多命令行选项和配置可以查看仓库根目录的 README.md 与示例配置文件 conf.json.EXAMPLE。七、总结✅param / returns / type是日常使用频率最高的三件套✅class / property / typedef用于构建类和复杂类型文档✅example / throws / since / deprecated让文档专业度直接拉满✅ 标签的权威定义都在 packages/jsdoc-tag/lib/definitions/core.js遇到不确定的写法可对照源码掌握这 15 个标签你的 JSDoc 注释规范就已经超过 90% 的 JavaScript 项目。现在就把这份速查清单收藏起来下次写代码时按需取用吧 【免费下载链接】jsdocAn API documentation generator for JavaScript.项目地址: https://gitcode.com/gh_mirrors/js/jsdoc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 JSDoc注释规范详解：@param、@return、@type等15个必会标签一次学会
JSDoc注释规范详解param、return、type等15个必会标签一次学会【免费下载链接】jsdocAn API documentation generator for JavaScript.项目地址: https://gitcode.com/gh_mirrors/js/jsdocJSDoc 是 JavaScript 开发者最常用的API 文档生成器An API documentation generator for JavaScript它通过解析源码中的/** ... */块注释自动产出结构化的 API 文档。本文带你一次学会 JSDoc 注释规范中最核心的 15 个标签——param、returns、type、class 等让你写的注释既规范又高效。一、JSDoc 是什么为什么必学JSDoc的工作流程非常简单你在函数、类、变量上方写注释 → 运行 jsdoc.js 命令行工具 → 自动生成 HTML 文档站点。它的核心优势文档与代码同处一仓注释即文档永远不会过期脱节零学习成本入门会写注释就会写 JSDocIDE 原生支持VS Code 等编辑器能读取 JSDoc 提供自动补全和类型提示️模块化架构核心标签定义在 core.js 中标签体系清晰可扩展 一句话记忆注释里用标签声明参数、返回值和类型JSDoc 就能自动生成专业文档。二、JSDoc 注释的基本格式一条 JSDoc 注释遵循固定结构以/**开头注意必须是块注释不是//第一行写一句话描述会成为文档标题空行后跟若干标签行以*/结尾/** * 按名称查找用户。 * * param {string} name 要查找的用户名 * returns {object} 匹配到的用户对象 */ function findUser(name) { /* ... */ }标签的官方定义全部集中在 packages/jsdoc-tag/lib/definitions/core.js每个标签都声明了是否必须带值、能否带类型等约束。三、15个核心标签速查手册1. param —— 声明函数参数最高频param用于描述函数的每一个参数格式为param {类型} 名称 描述/** * param {string} targetName 要查找的目标名称 * param {function} callback 回调函数 */ function find(targetName, callback) {}小贴士可选参数用方括号param [asynctrue] 是否异步执行联合类型用|param {string|number} xarg、argument都是它的别名更多变体可参考 paramtag.js2. returnsreturn—— 声明返回值returns描述函数的返回值类型和含义return是它的简写别名/** * 查找目标并返回结果列表。 * returns {string|Arraystring} 找到的目标名称 */ function find(targetName) {}参考示例returnstag.js。3. type —— 声明变量/属性的类型给变量或对象属性显式标注类型/** * type {number} 当前计数器 */ let count 0;注意type 后面只能跟类型表达式不能跟描述文字这是 core.js 中mustNotHaveDescription的硬约束。4. typedef —— 定义可复用类型复杂对象类型建议用typedef先起名之后到处引用/** typedef {string|number} calc.NumberLike */ /** param {calc.NumberLike} x 数字或字符串 */ function readNumber(x) {}这样避免了长类型表达式反复书写维护性大幅提升。实战示例见 typedeftag.js。5. class —— 标记构造函数为类/** * 描述 Ticker 类的功能。 * class */ var Ticker function() {};在函数式构造函数上标注class后JSDoc 才会把它当作类来归类展示。示例见 classtag.js。6. property —— 描述对象的属性给类或对象属性补充类型与说明/** * property {string} hostname 服务器地址 * property {number} port 端口号 */ function MySocket() {}7. example —— 提供使用示例example允许在文档中嵌入代码示例支持重复使用多次JSDoc 会自动保留其中的空白格式/** * 创建任务并执行。 * example * const task new Task(build); * task.run(); */ function Task(name) {}8. throwsexception—— 声明可能抛出的异常/** * throws {InvalidArgumentException} 参数非法时抛出 */ function foo(x) {}exception是throws的别名两者完全等价。完整示例见 exceptiontag.js。9. since —— 标注引入版本/** * since 2.0.0 */ function newFeature() {}方便使用者快速判断我用的版本是否包含这个 API。10. deprecated —— 标记废弃 API/** * deprecated 请改用 {link findUser} */ function oldFindUser() {}带值说明替代方案时效果最好——文档中会直接显示弃用提示横幅。11. author —— 标注作者可重复使用多次书写会累加成数组/** * author 张三 * author 李四 lisiexample.com */ function coreApi() {}12. see —— 关联相关文档在文档中建立延伸阅读链接/** * see {link findUser} 查找函数的文档 */ function helper() {}13. module —— 声明模块把若干导出归入同一逻辑模块/** * 用户管理模块。 * module user-manager */配合exports使用可将一组函数打包成统一的模块文档页。14. ignore —— 从文档中排除对纯内部实现、不想出现在公开文档中的代码加一行即可隐身/** ignore */ function _internalHelper() {}15. summary —— 一句话摘要在长描述之外提供独立的摘要字段方便文档目录展示/** * 完整的详细描述…… * summary 快速计算两个数的和 */ function add(a, b) {}四、一份完整的标准答案模板把常用标签组合起来就是一个生产级函数的标准注释模板/** * 根据条件查询用户列表。 * * param {string} name 用户名支持模糊匹配 * param {number} [limit10] 返回条数上限 * returns {Arrayobject} 用户对象数组 * throws {InvalidArgumentException} name 为空时抛出 * since 1.2.0 * author JSDoc Team * see {link createUser} * example * const users findUsers(zhang, 5); */ function findUsers(name, limit) {}五、新手常见错误清单 ⚠️错误正确做法用//或/* */写注释必须用/** */块注释忘记returns的类型大括号写returns {string}而非returns stringtype后加了描述文字type {object}单独一行描述写在注释第一行参数顺序与函数签名不一致param顺序应与函数形参一一对应拼写return时漏了类型return也支持带类型建议统一用returns六、下一步如何运行 JSDoc 生成文档# 安装项目依赖并运行 git clone https://gitcode.com/gh_mirrors/js/jsdoc cd jsdoc nvm install npm link jsdoc your-file.js运行后会自动输出 HTML 文档。更多命令行选项和配置可以查看仓库根目录的 README.md 与示例配置文件 conf.json.EXAMPLE。七、总结✅param / returns / type是日常使用频率最高的三件套✅class / property / typedef用于构建类和复杂类型文档✅example / throws / since / deprecated让文档专业度直接拉满✅ 标签的权威定义都在 packages/jsdoc-tag/lib/definitions/core.js遇到不确定的写法可对照源码掌握这 15 个标签你的 JSDoc 注释规范就已经超过 90% 的 JavaScript 项目。现在就把这份速查清单收藏起来下次写代码时按需取用吧 【免费下载链接】jsdocAn API documentation generator for JavaScript.项目地址: https://gitcode.com/gh_mirrors/js/jsdoc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考