开发工具文档【免费下载链接】jsdocAn API documentation generator for JavaScript.项目地址https://gitcode.com/gh_mirrors/js/jsdoc点击查看免费下载本文以仓库根目录的 CHANGES.md 为蓝本系统梳理 JSDocJavaScript API 文档生成器从 3.0.0 到 4.0.0 十余年间的版本演进脉络并结合当前仓库的源码、配置与测试资源逐一还原每个版本引入的解析能力、标签体系、CLI 参数、配置项与插件生态。读完本文你将理解 JSDoc 在 Node.js 兼容性、ECMAScript 2015 语法支持、Closure Compiler 类型系统、模板与插件机制等关键维度上的完整演变过程并掌握如何利用配置与命令行参数把这些能力落到实际文档生成工作中。一、CHANGES.md 是什么一份可追溯的版本档案CHANGES.md是 JSDoc 官方维护的变更历史文件明确说明本文件描述 JSDoc 自 3.0.0 起每个版本的重要变化原文档英文标题为 JSDoc change history。它不仅是用户升级时的对照手册也是理解 JSDoc 架构演进的权威史料从 3.0.02012 年 5 月初始发布到 4.0.02022 年 11 月每个版本记录的内容可分为几类主要变化Major changes运行时环境、解析器、语义版本策略等影响面最大的变更增强Enhancements新增的配置项、CLI 参数、标签解析能力Bug 修复Bug fixes针对 ES2015 类/模块、类型表达式、插件、模板的具体问题插件Plugins与模板改进Template improvements官方插件与默认模板/Haruki 模板的行为变化。阅读本档案时可配合仓库中的 README.md、packages/jsdoc/conf.json.EXAMPLE 与各packages/子包源码交叉印证例如配置项的实际默认值可以追溯到 packages/jsdoc-core/lib/config.js 中的defaultConfig对象命令行参数的精确语义可以追溯到 packages/jsdoc-cli/lib/flags.js。二、4.0.02022 年 11 月语义化版本与 TaffyDB 告别4.0.0 是 JSDoc 进入新纪元的里程碑版本CHANGES.md 记录了三条核心变化采用语义化版本SemVer今后若 JSDoc 出现不向后兼容的变更主版本号major version会相应递增用户可以根据版本号预判升级风险。彻底移除taffydb依赖这是 4.0.0 最具影响力的内部重构。如果用户自研的模板或插件仍在引用taffydb包需要迁移到替代包jsdoc/salty。支持 Node.js 12.0.0 及以上把运行时下限统一抬升到 Node.js 12。2.1 为什么用 Salty 替换 TaffyDB要理解这次替换的意义需要看仓库中 packages/jsdoc-salty/README.md 的完整说明JSDoc 3.x 长期使用 TaffyDB 管理 doclet描述代码信息的对象——解析完代码后JSDoc 会把 doclets 以 TaffyDB 对象的形式交给模板模板再通过 TaffyDB 查询删除无用 doclet、检索生成文档所需的数据。替换的原因有二TaffyDB 早已无人维护且存在公开的 CVE-2019-10790 记录虽然 JSDoc 只把代码自身的元数据存于内存、不落盘实际并不构成真实安全风险但存在 CVE本身就足以让安全审查与依赖扫描工具报警TaffyDB 的许可证声明长期自相矛盾README 声称使用 1-clause BSDpackage.json声称 2-clause BSD而 License 文件又声称 MIT造成合规性隐患。Salty 是只支持 JSDoc 历史上用到的那些 TaffyDB 特性的裁剪版实现采用 Apache 2.0 许可证同时解决了安全审查噪音与许可证不确定性。2.2 把自定义模板从 taffydb 迁移到 jsdoc/salty如果使用 JSDoc 4.0.0 自带模板无需任何改动只有自定义模板才需要迁移packages/jsdoc-salty/README.md 给出了五步操作在模板的publish.js中定位require(taffydb)语句常见写法为const taffy require(taffydb).taffy;或const { taffy } require(taffydb);把包名替换为jsdoc/salty即const { taffy } require(jsdoc/salty);从模板的package.json中删除taffydb依赖在模板的package.json中新增jsdoc/salty依赖在模板目录执行npm install并验证模板行为。迁移后模板仍可与 JSDoc 3.x 兼容。需要注意的是Salty 只支持 TaffyDB 的查询、排序、迭代、删除等子集能力排序顺序比 TaffyDB 更可预测非空值按标准序 → 空值 → 显式 undefined → 隐式 undefined。三、3.6.x 系列2019—2022兼容性维护期3.6.x 是发布最频繁的维护分支CHANGES.md 记录的重点如下3.6.112022 年 7 月更新依赖版本使其与 Node.js 12.0.0 及更高版本兼容3.6.102022 年 1 月修复 3.6.9 在部分 CI 环境无法安装的问题3.6.92022 年 1 月修复npm install jsdoc无法工作的问题3.6.8 / 3.6.7 / 3.6.4 / 3.6.3 / 3.6.2 / 3.6.1以依赖更新为主其中 3.6.2 修复 ES2015 类不出现在生成文档中的问题3.6.1 防止 Node.js 12 下使用类型应用type applications时崩溃3.6.62020 年 9 月修复既是 ES2015 类又被赋值给变量的接口interface成员跟踪错误例如/** interface */ foo.Bar class { constructor() { /** 此前该成员会从生成文档中缺失 */ this.baz null; } };3.6.52020 年 7 月当两个函数参数使用相同的类型表达式且带有--debug标志时防止 doclet 出现循环引用3.6.02019 年 5 月兼容 Node.js 12 并要求 Node.js 8.15.0同时识别全部已文档化的 Closure Compiler 标签。3.1 3.6.0 的增强与修复要点3.6.0 引入了几个至今常用的配置能力templates.useShortNamesInLinks链接文本显示符号的短名如baz而非完整 longname如foo.bar.bazMarkdown 插件支持自定义代码块的语法高亮函数默认模板把命名空间namespaces放到 TOC 靠前位置修复了给 ES2015 构造函数添加 JSDoc 注释时丢失除 description 与 params 之外标签的问题exports与enum组合使用时可正常工作Markdown 插件中语言标记为plain的代码围栏不再被 pretty-print。四、3.5.02017 年 7 月Babylon 解析器与新标签时代3.5.0 是 JSDoc 解析能力质变的一次大版本CHANGES.md 用大篇幅记录了这次升级。4.1 解析器切换与 ECMAScript 新语法支持JSDoc 改用 BabylonBabel 的 JavaScript 解析器因此能够解析 Babel 编译器支持的任何 JavaScript 或 JSX 文件包括装饰器Decorators公有与私有类字段class fields异步迭代器async iterators动态import()可选链optional chaining。同时JSDoc 也由此可以解析异步函数async function foo() {}并自动检测其为异步自动检测生成器函数generator functions。当前仓库的解析链路中sourceType会经 packages/jsdoc-parse/lib/parser.js 传入 packages/jsdoc-ast/lib/ast-builder.js 的build(source, filename, sourceType)方法参与构建 AST与这段历史一脉相承。4.2 新标签async、generator、hideconstructor、package、yields3.5.0 新增五个标签官方提示第三方模板可能不支持这些新标签async标记异步函数。一般情况下无需使用因为 JSDoc 会自动检测以async function foo() {}声明的函数generator标记生成器函数同样可被自动检测通常无需手写hideconstructor在文档中隐藏类的构造函数package标记符号为包私有package-privateyields文档化生成器函数产出的值。这些标签的定义可继续在 packages/jsdoc-tag/lib/definitions/jsdoc.js 中查看对应的测试夹具与测试规格分别位于 packages/jsdoc/test/fixtures 与 packages/jsdoc/test/specs/tags。4.3 新增配置项与事件字段sourceType控制 JS 文件解析方式默认值module设为script可抑制隐式严格模式但也会禁止使用 ES2015 模块。这一默认值在当前仓库的 packages/jsdoc-core/lib/config.js 中依然可见sourceType: module且 packages/jsdoc-cli/test/fixtures/configs/conf.json 中也有sourceType: script的测试用例recurseDepth控制 JSDoc 递归搜索文件的层数默认值 10JS 配置文件可以用 JavaScript 文件配置 JSDoc该文件必须是导出单个配置对象的 CommonJS 模块事件增强jsdocCommentFound与symbolFound事件新增columnno属性报告注释或符号所在的列号无法解析类型表达式时日志会输出类型表达式所在行号。4.4 3.5.0 的主要 Bug 修复ES2015 类的构造函数与实例属性可被正确文档化从 ES2015 模块导出的类的构造函数、导出符号及其子符号的 scope 均正确修复 UTF-8 JSON 文件带 BOM 时崩溃、author标签无值崩溃、函数赋给变量时默认/可重复参数自动检测等问题JSDoc 退出时总是调用process.exit()。五、3.4.x2015—2016Node.js 化与模板体系完善3.4.32016 年 11 月更新 LICENSE 文件3.4.22016 年 10 月修复 ES2015 模块导出类的文档化、插件与模板加载、实验性对象展开运算符导致的崩溃3.4.12016 年 9 月tags.allowUnknownTags配置现在可以接受一个允许的标签名数组默认模板为表格采用合适的样式新增silent模板不生成任何输出便于把 JSDoc 当作linter检查注释语法错误与无法识别的标签3.4.02015 年 11 月JSDoc 正式放弃 Mozilla Rhino仅支持在 Node.js 4.0.0 上运行可以解析 ECMAScript 2015 原生类与模块、JSX 文件const声明被自动视为常量app与env全局变量被弃用改用jsdoc/env模块模板的publish方法可返回 Promise从而支持异步模板。3.4.0 还带来了 Markdown 插件的markdown.idInHeadings配置为标题自动生成 heading ID、默认模板的templates.default.useLongnameInNav配置导航栏显示完整 namepath等细节。六、3.3.02015 年 5 月Node.js 运行能力与接口标签落地3.3.0 标志着 JSDoc 可以在 Node.js 上运行#93并引入一组沿用至今的接口语义interface与implements标签文档化接口及其实现支持 Closure Compiler 的inheritDoc与override符号带mixes标签时所有 mixin 都会出现在文档中--verbose标志运行中向控制台记录信息如每个解析文件的名字-P/--package与-R/--readme标志可指定任意文件作为文档的 package 或 README 文件--pedantic标志把所有错误视为致命错误、把警告视为错误取代了含义相反的--lenient-a/--access标志控制私有、受保护与公有符号是否出现在文档中。当前 packages/jsdoc-cli/lib/flags.js 中这些标志的定义仍然完整access别名a可选值all/package/private/protected/public/undefined默认除 private 外全部、pedantic、verbose、debug、package别名P、readme别名R等一应俱全。6.1 配置体系增强3.3.0 起配置系统显著增强多数能力沿用至今配置文件可以包含 JavaScript 注释JSON 注释形式source.exclude支持排除-r/--recurse扫描时的子目录-r模式下教程tutorials也递归扫描tags.dictionaries可启用 Closure Compiler 专用标签字典取值可为jsdoc、closure或两者多字典启用时若某标签在多个字典中有定义JSDoc 采用第一个包含该标签的字典中的定义。当前 packages/jsdoc-core/lib/config.js 的默认值为dictionaries: [jsdoc, closure]覆盖符号的 doclet 会新增overrides属性内含被覆盖符号的 longnamedoclet 的type对象会包含隐藏的parsedType属性即由 Catharsis 生成的类型表达式语法树格式未来可能变化输出文件名允许非 ASCII 字符必要时 URL 编码输出文件不以前导下划线开头id属性尽量保证文件内唯一无输入文件或命令行选项无法识别时JSDoc 会显示用法信息。6.2 3.3.0 的插件与模板改进插件方面标签定义可增加mustNotHaveDescription属性为真时标签文本含描述将告警新增summarize插件根据描述自动生成摘要与underscore插件自动把以下划线开头的符号标记为privateMarkdown 插件默认把author与throws标签值转换为 HTML且不再阻止内联{link}标签工作。模板方面可通过templates.default.layoutFile覆盖主布局layout.tmpltemplates.default.outputSourceFiles: false可隐藏源码路径templates.default.staticFiles.include可复制额外静态文件到输出目录staticFiles.paths已弃用templates.default.includeDate: false可隐藏页脚日期美化打印的源码带行号example中的文本含 HTML 标签会被正确转义。这些插件目前仍以独立文件形式存在于 packages/jsdoc-plugins 目录中如 summarize.js、underscore.js、comments-only.js、partial.js、event-dumper.js、overload-helper.js 等。七、3.2.x2013Closure Compiler 类型表达式与事件系统7.1 3.2.02013 年 5 月可解析任何合法的 Google Closure Compiler 类型表达式相应地文件含非法类型表达式时 JSDoc 会退出可用--lenient-l标志阻止退出新增listens标签标记符号监听某个事件解析器新增parseBegin事件开始解析前触发处理器可修改待解析文件列表与parseComplete事件全部解析后触发jsdocCommentFound事件处理器现在可以修改 JSDoc 注释新增markdown.excludeTags配置从 Markdown 处理中排除指定标签typedef配合 Closure 风格类型定义时可省略名称自动获得Foo.Bar这类名称参数描述中可使用内联{type}标签例如param {(boolean|string)} myParam - My special parameter. {type Foo}会把myParam的类型记录为Foo新插件overloadHelper便于链接到重载方法markdown 插件转换see中的 Markdown 链接。7.2 3.2.12013 年 10 月与 3.2.22013 年 11 月解析器新增processingComplete事件全部后处理完成后触发带doclets属性parseComplete事件也新增doclets属性配置文件source.exclude支持相对路径相对当前工作目录解析带default标签且默认值为对象字面量时值以字符串存储并附defaultvaluetype: object便于模板做语法高亮内联{link}可包含换行JS 文件首行 hashbang如#!/usr/bin/env node会被忽略let等 JS 1.8 关键字不再导致崩溃继承符号会指明其真正的定义祖先而非直接父类默认模板默认生成美化打印的源码文件可用templates.default.outputSourceFiles: false关闭源码链接可跳转到符号定义行default对象值会显示在输出文件中。八、3.1.02013 年 1 月callback 标签与链接标签体系3.1.0 引入至今常用的callback标签用于描述回调函数签名——先创建独立的 JSDoc 注释再通过 namepath 引用/** * class */ function MyClass() {} /** * Send a request. * * param {MyClass~responseCb} cb - Called after a response is received. */ MyClass.prototype.sendRequest function(cb) { // code }; /** * Callback for sending a request. * * callback MyClass~responseCb * param {?string} error - Information about the error. * param {?string} response - Body of the response. */内联链接标签也大幅改进{link}支持用空格分隔链接目标与链接文本配置项templates.cleverLinks代码链接用等宽字体、URL 链接用普通文本与templates.monospaceLinks所有链接用等宽字体——注意模板需相应更新才能生效新增{linkplain}强制普通文本链接与{linkcode}强制等宽链接二者总是覆盖conf.json中的设置。此外3.1.0 提供了-l/--lenient选项遇到非致命错误继续运行模板的publish.js应把 publish 函数赋给exports.publish而非定义全局函数模板辅助函数从默认模板中提取为templateHelper.js新增-v/--version选项显示版本号测试支持--nocolor禁用彩色输出。3.1.0 还新增了一批新插件partial支持partial标签链接到包含 JSDoc 注释的外部文件commentsOnly删除文件中除 JSDoc 注释外的所有内容可用于文档化并非合法 JavaScript的源码如其他语言源码eventDumper向控制台记录解析器事件信息verbose向控制台记录每个输入文件名。九、3.0.x2012初始发布与基础配置3.0.02012 年 5 月初始发布JSDoc 3 时代的开端3.0.12012 年 6 月conf.json支持source.include与source.exclude——前者指定总是检查的文件/目录后者指定永不检查的文件/目录二者优先级高于基于正则的source.includePattern/source.excludePattern-t/--template支持绝对路径。十、跨版本沉淀的实战清单10.1 配置文件格式与默认值综合各版本演进JSDoc 配置体系已支持多种来源JSON 配置文件可含注释、CommonJS/ES2015 模块导出的配置对象、.jsdocrcJSON/YAML、jsdoc.config.js以及package.json中的jsdoc字段。当前 packages/jsdoc-core/lib/config.js 中的defaultConfig提供了权威默认值配置项默认值说明opts.destination./out文档输出目录不存在时自动创建opts.encodingutf8源文件字符编码sourceTypemodule源文件类型仅 ES5 语法时可用scripttags.allowUnknownTagstrue是否允许无法识别的标签tags.dictionaries[jsdoc, closure]标签字典多字典时取第一个包含该标签者plugins[]要加载的插件路径templates.cleverLinksfalse代码链接用等宽字体templates.monospaceLinksfalse所有链接用等宽字体仓库中的 packages/jsdoc/conf.json.EXAMPLE 给出了最小可运行示例{ tags: { allowUnknownTags: true }, source: { includePattern: .\\.js(doc|x)?$, excludePattern: (^|\\/|\\\\)_ }, plugins: [], templates: { cleverLinks: false, monospaceLinks: false, default: { outputSourceFiles: true } } }10.2 CLI 参数速查结合 packages/jsdoc-cli/lib/flags.js 中的定义历次版本沉淀的主要命令行参数如下长参数短参数说明--access-a只文档化指定访问级别的符号all/package/private/protected/public/undefined--configure-c指定配置文件--debug—输出帮助调试的信息--destination-d输出目录默认./out--encoding-e读取源文件时采用的编码默认utf8--explain-X把解析结果打印到控制台并退出--help-h打印帮助并退出--package-P指定使用的package.json路径--pedantic—把错误视为致命错误、把警告视为错误--private-p文档化私有符号等价于--access all--query-q解析并存储查询字符串如foobarbaztrue--readme-R指定要包含进文档的 README 文件--template-t指定使用的模板包--verbose—向控制台输出详细信息--version-v显示版本号并退出历史版本还记录过-r/--recurse递归搜索输入目录、-l/--lenient非致命错误继续运行后被--pedantic取代、-p/--private等参数的引入与语义调整使用前请以当前版本的--help输出为准。10.3 值得沿用的配置与插件组合把 JSDoc 当 linter 用配合silent模板3.4.1 引入检查注释中的语法错误与无法识别的标签异步/生成器函数检测3.5.0 起自动检测无需手写async/generator接口与继承语义interface、implements、mixes、inheritDoc、override构成完整的面向对象文档能力插件全家桶summarize自动摘要、underscore自动私有化、overloadHelper重载链接、eventDumper事件日志、commentsOnly非 JS 源码文档化可按需加载。十一、升级与迁移建议从 CHANGES.md 提炼的注意事项先确认 Node.js 版本4.0.0 要求 Node.js 12而当前仓库根目录 package.json 的engines字段要求 Node.js^22.13.0 || 23.0.0说明项目的开发环境已随生态继续前进升级前应核对自身运行环境模板与插件检查 TaffyDB 引用若模板/插件仍引用taffydb按本文 2.2 节迁移到jsdoc/salty关注新标签支持度3.5.0 起新增的async、generator、hideconstructor、package、yields等标签第三方模板可能不支持升级模板前需确认配置项兼容性--lenient已被--pedantic取代staticFiles.paths已弃用改用staticFiles.includejsVersion配置在 3.2.0 已移除把本文件作为回归对照CHANGES.md 中每个版本的 Bug 修复列表都可作为升级后回归测试的检查清单。十二、延伸阅读仓库内的相关资源CHANGES.md本文依据的完整变更历史含各版本对应的 GitHub issue 引用packages/jsdoc-core/lib/config.js配置默认值与加载逻辑JSON/YAML/JS 配置、package.json的jsdoc字段packages/jsdoc-cli/lib/flags.js全部命令行参数定义packages/jsdoc/conf.json.EXAMPLE最小配置示例packages/jsdoc-salty/README.mdTaffyDB 替换的动机、迁移步骤与 Salty 支持的功能子集packages/jsdoc-pluginssummarize、underscore、partial、commentsOnly、eventDumper、overloadHelper 等官方插件packages/jsdoc/test/fixtures 与 packages/jsdoc/test/specs/tags与各标签、各版本新特性对应的测试夹具与规格。赞分享开发工具文档【免费下载链接】jsdocAn API documentation generator for JavaScript.项目地址https://gitcode.com/gh_mirrors/js/jsdoc点击查看免费下载相关推荐Diesel ORM 版本演进全解析从 2.3/2.4 新特性到 1.x 历史变更深度导读Diesel ORM 版本演进全解析从 2.3/2.4 新特性到 1.x 历史变更深度导读 Diesel 是 Rust 生态中主打“安全、可扩展”的 ORM后端数据库MikroORM 版本演进全解析从 7.x 核心特性到完整变更历史解读MikroORM 版本演进全解析从 7.x 核心特性到完整变更历史解读 MikroORM 是 TypeScript 生态中基于 Data Mapper、Uni后端BootstrapVue 历史版本演进全解析从 v0.17 到 v2.0.0-rc.28 的变更日志深度解读BootstrapVue 历史版本演进全解析从 v0.17 到 v2.0.0 rc.28 的变更日志深度解读 导读 CHANGELOG OLD.md http前端UI组件上一篇mathlib4中的环论交换环与非交换环的形式化理论下一篇终极智能家居项目实战从零开始构建完整设备控制与自动化系统创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考