文档CLI【免费下载链接】documentation:book: documentation for modern JavaScript项目地址https://gitcode.com/gh_mirrors/do/documentation点击查看免费下载导读documentation.js不仅提供documentation命令行工具还暴露了一套完整的 Node API让开发者可以在自己的脚本、构建工具如 gulp/grunt 插件或自定义集成中直接完成解析 JSDoc → 校验文档 → 生成 Markdown/JSON/HTML的完整流水线。阅读本文后你将掌握lint、build、formats三大 API 的签名、参数语义与返回值并能基于源码理解其底层执行链路写出可复用的文档生成与校验脚本。docs/NODE_API.md是 documentation.js 通过自我文档化self-hosted生成的 Node API 参考仓库的doc脚本执行node ./bin/documentation.js build src/index.js -f md --accesspublic docs/NODE_API.md见 package.json即用自己解析自己的入口模块。因此本文所有 API 签名、参数与示例均与 src/index.js 中的真实实现一一对应可直接作为开发参考。一、总体设计两阶段管道模型从 Node API 的角度看documentation.js 的生成流程被清晰地拆成两个阶段解析阶段documentation.build/documentation.buildSync接收入口文件entry points产出已解析的 JSDoc 注释列表一组结构化的 comment 对象附带推断出的类型、参数、成员关系等信息输出阶段documentation.formats.md、documentation.formats.json、documentation.formats.html等格式方法接收这批 comments产出字符串Markdown / JSON或 Vinyl 风格对象HTML等最终结果。此外documentation.lint是一个独立的校验入口用于检查文档中非标准或错误的信息。这一解析 输出的管道模型在 src/index.js 中体现得非常清晰build走buildInternallint走lintInternal两者共用configure配置合并与expandInputs输入展开的前置流程但后续的 comment 处理管道pipeline不同。Node API 的典型适用场景与 docs/USAGE_NODE.md 描述一致构建集成例如基于 documentation.js 定制 gulp 或 grunt 插件复用其 AST 解析或其他组件如expandInputs、util.createFormatters、util.LinkerStack编写自定义的文档生成、校验或统计分析工具mad science。二、lint校验文档的非标准与错误信息2.1 签名与参数documentation.lint(indexes, args) Promiseindexesstring | Arraystring要处理的文件列表也接受 glob 模式。argsObject可配置项完整列表如下参数类型默认值说明externalArraystring—字符串正则 / glob 匹配模式用于定义哪些外部模块会被白名单放行并纳入生成的文档shallowbooleanfalse是否跳过依赖解析shallow 模式只处理显式指定的文件inferPrivatestring—合法的正则表达式字符串根据命名结构推断代码元素是否为私有。例如设置inferPrivate: ^_会自动把_myMethod这类命名的方法视为私有extensionstring \| Arraystring—将额外文件扩展名当作 JavaScript 解析扩展默认集合js、es6、jsx2.2 返回值与用法示例lint返回一个 Promiseresolve 为一个可能为空的 lint 信息字符串设计用于人类可读输出。官方示例documentation.lint(file.js).then(lintOutput { if (lintOutput) { console.log(lintOutput); process.exit(1); } else { process.exit(0); } });即若有 lint 输出则打印并返回非零退出码否则以 0 退出非常适合接入 CI 校验。2.3 底层实现lint 管道到底检查什么从源码看lintInternal执行的管道为lintComments → inferName → inferAccess → inferAugments → inferKind → inferParams → inferProperties → inferReturn → inferMembership → inferType → nest见 src/index.js核心规则位于 src/lint.js类型命名规范化检查CANONICAL映射表定义了一批非标准的类型写法例如String应写成string、Boolean应写成boolean、Undefined应写成undefined、array应写成Array、date应写成Date、object应写成Object。命中时会产出type X found, Y is standard类警告类型结构的递归检查checkCanonical会递归进入elements与applications覆盖泛型、联合类型等嵌套场景参数名推断比对显式声明的param foo若与从代码推断出的参数列表不匹配会产生警告对应测试夹具tests/fixture/lint/lint.output 中大量An explicit parameter named foo was specified but didnt match inferred information a, b的输出。formatLint将错误信息汇总到vfile并通过vfile-reporter渲染为带行号的终端报告。测试用例tests/index.js 验证了对合法注释调用lint返回空字符串tests/bin.js 则验证了命令行documentation lint在坏文件上会输出警告、在好文件上无输出、在语法错误文件上以非零码退出等行为。三、build生成结构化的文档数据3.1 签名与参数documentation.build(indexes, args) PromiseArrayObjectindexes与lint相同string | Arraystring也支持对象形式{ source, file }见 src/input/shallow.js。args可配置项如下参数类型默认值说明externalArraystring—外部模块白名单正则 / glob 模式shallowbooleanfalse是否跳过依赖解析只处理指定文件sortOrderArraystring \| Object[]定义文档的排序顺序可选值见下文accessArraystring[]实际默认[public, undefined, protected]输出到文档的访问级别集合hljsObject—highlight.js 可选参数hljs.highlightAutobooleanfalse是否让 highlight.js 自动检测代码语言hljs.languagesArray—供 highlight.js 选择的语言集合inferPrivatestring—推断私有成员的正则字符串extensionstring \| Arraystring—额外按 JavaScript 解析的扩展名3.2 返回值与用法示例返回 Promiseresolve 为带推断属性的已解析注释数组即文档生成或任何其他代码数据分析所需的一切。官方示例var documentation require(documentation); documentation.build([index.js], { // only output comments with an explicit public tag access: [public], sortOrder: [kind, alpha] }).then(res { // res is an array of parsed comments with inferred properties // and more: everything you need to build documentation or // any other kind of code data. });3.3 底层实现build 的执行链路build的完整链路见 src/index.js配置合并configure调用mergeConfig将程序参数、配置文件--config指定的 yml/json以及最近的package.json中的name、homepage、version、description合并为project-*前缀配置见 src/merge_config.js输入展开expandInputs依据config.shallow或config.documentExported决定走 src/input/shallow.js不解析依赖支持{ source, file }对象输入可在无文件系统的浏览器环境运行还是 src/input/dependency.js基于 module-deps 的依赖解析需要文件系统访问级别默认值若未显式提供config.access默认设为[public, undefined, protected]解析与推断管道对每个输入文件调用parseJavaScriptsrc/parsers/javascript.js随后逐个执行inferName、inferAccess、inferAugments、inferImplements、inferKind、nest、inferParams、inferProperties、inferReturn、inferMembership、inferType等推断器若启用了 GitHub 链接推断还会执行github最后garbageCollect清理无效节点排序与访问过滤sort(extractedComments, config)排序后经hierarchy构建嵌套结构再由filterAccesssrc/filter_access.js按访问级别过滤——private注释会被剔除除非访问级别列表显式包含private。关于buildSyncdocs/USAGE_NODE.md 中提到了documentation.buildSync它接收{ source, file }对象数组作为入口例如source: /** hi this is a doc\nname myDoc */, file: direct.js是同步变体适合不依赖文件系统的内存输入场景。从源码结构看返回的 comment 对象包含descriptionremark 风格的 Markdown ASTtype: root加children、tags、loc源码位置、augments、examples、implements、params、properties、returns、sees、throws、todos、yields、name、members按events/global/inner/instance/static分组的嵌套成员、path、namespace等字段。这些字段的初始结构在 src/parse.js 中定义完整结构可参考快照tests/snapshots/index.js.snap。JSDoc 标签规范化的关键实现位于 src/parse.js文档中对param、returns、property、throws、example、augments等标签会扁平化为params、returns、properties等数组字段同时支持大量同义词映射例如virtual⇢abstract、extends⇢augments、constructor⇢class、const⇢constant、defaultvalue⇢default、desc⇢description、arg/argument⇢param、prop⇢property、return⇢returns、exception⇢throws、emits⇢fires、func/method⇢function、var⇢member等access/public/protected/private则被扁平化为access属性默认视为public。3.4 排序sortOrder 的取值语义sortOrder的可选值与 CLI 中的--sort-order一致见 src/sort.jssource按源码位置context.sortKey排序默认值alpha按名称name字母序kind按注释种类kind排序access按访问级别排序memberof按所属模块memberof排序。另外 src/sort.js 支持基于toc配置的显式排序documentation.yml中toc条目可以是名称字符串按索引排到固定位置或带name/description/file/children的对象kind会被设为note可作为叙述性章节插入文档。四、formats模块化的输出格式formats是 documentation.js 的格式命名空间见 src/index.js包含html、md、remark、json四个方法。它们都是接收 comments 与 config、返回 Promise的模块化方法输入为解析后的注释数组输出为字符串化的 JSON、Markdown 字符串或 HTML 的 Vinyl 对象等。4.1 formats.html生成 HTMLformats.html(comments, config) PromiseArrayObject参数类型默认值说明commentsArrayComment—解析后的注释数组来自buildconfig.themestringdefault_theme用作 HTML 主题的模块名称官方示例var documentation require(documentation); documentation.build([index.js]) .then(documentation.formats.html);实现细节src/output/html.jshtml会再次调用mergeConfig合并配置若指定了config.theme则通过动态import()加载该主题模块并调用其默认导出主题模块签名为(comments, config) PromiseArrayObject否则加载内置主题 src/default_theme/index.js。返回的是一组 Vinyl 对象含index.html等文件通常配合-o输出目录使用。在 Windows 平台上绝对主题路径会被加上file:///前缀以避免ERR_UNSUPPORTED_ESM_URL_SCHEME错误。主题定制可参考 docs/THEMING.md。4.2 formats.markdown生成 Markdownformats.markdown(comments, args) Promisestringcomments为解析后的注释数组args为可定制输出的选项对象。官方示例var documentation require(documentation); var fs require(fs); documentation.build([index.js]) .then(documentation.formats.md) .then(output { // output is a string of Markdown data fs.writeFileSync(./output.md, output); });实现细节src/output/markdown.jsmarkdown内部先把 comments 交给markdownASTsrc/output/markdown_ast.js生成 remark 兼容的 AST——包括开头的!-- Generated by documentation.js. ... --注释、可选的 Table of Contents 标题config.markdownToc默认开启markdownTocMaxDepth默认 6、GitHub 源码链接、类型 / 参数 / 属性 / 示例 / Throws / Returns / Meta 等章节随后用remark().use(remarkGfm).stringify(ast)渲染为最终字符串。remark-gfm的引入意味着 Markdown 输出支持 GFM 扩展如表格这由tests/bin.js 中 build GFM (e.g. markdown tables) 的测试验证。markdownAST还负责代码高亮配置config.hljs透传给highlight.jshighlightAuto开启时自动检测示例代码语言、链接重路由rerouteLinksLinkerStack可将{link}等引用链接到目标注释的锚点。4.3 formats.json生成 JSONformats.json(comments) Promisestringcomments为解析后的注释数组返回 Promiseresolve 为 JSON 字符串。官方示例var documentation require(documentation); var fs require(fs); documentation.build([index.js]) .then(documentation.formats.json) .then(output { // output is a string of JSON data fs.writeFileSync(./output.json, output); });实现细节src/output/json.jsjson在序列化前会遍历注释树删除errors字段以及context.sortKey这些属于过程性数据不适合出现在输出中然后用JSON.stringify(comments, null, 2)生成带缩进的字符串。快照tests/snapshots/index.js.snap 展示了build结果经formats.json序列化后的完整 JSON 结构示例。4.4 formats.remark输出中间 AST除了文档 docs/NODE_API.md 中列出的三个格式外源码 src/index.js 还暴露了formats.remark它返回markdownAST生成的 AST 并JSON.stringify(res, null, 2)适合需要拿到结构化文档树做二次加工如自定义渲染器、统计分析的场景。五、从参数到行为几个值得注意的语义external白名单声明为Arraystring用字符串正则 / glob 匹配模式定义哪些外部模块会被白名单放行并纳入文档。默认情况下外部模块会被过滤module_filters.js的internalOnly只有匹配白名单的才会进入生成结果shallow与依赖解析shallow: true会完全绕过依赖解析甚至对 JavaScript 代码本身也不解析依赖只处理显式传入的文件。测试用例tests/index.js 验证了expandInputs在深浅两种模式下都能正确展开输入inferPrivate的命名推断传入合法正则如^_后命名匹配该正则的成员会被推断为私有并在后续访问过滤中被剔除extension扩展解析范围默认解析扩展名集合为[.mjs, .js, .jsx, .es5, .es6, .vue, .ts, .tsx]见 src/config.jsextension参数在此之上追加新的扩展名。测试tests/bin.js 验证了通过--requireExtensionotherextension --parseExtensionotherextension解析自定义扩展名的行为access过滤语义src/filter_access.js 表明kind note的叙述性节点始终保留其余节点仅当!comment.ignore且访问级别在列表中时保留。CLI 帮助docs/USAGE.md中--access的可选值为public、private、protected、undefinedhljs代码高亮hljs.highlightAuto开启后markdownAST会用highlight.js自动检测示例代码的语言避免所有示例都被标记为javascripthljs.languages限制可检测的语言集合。六、实战用 Node API 构建一个文档生成脚本结合以上 API一个完整的解析 → 输出脚本可以这样组织var documentation require(documentation); var fs require(fs); // 1. 解析入口文件生成结构化注释数据 documentation.build([index.js], { access: [public, protected, undefined], sortOrder: [kind, source], shallow: false }) .then(function (comments) { // 2. 同时输出 Markdown 与 JSON return Promise.all([ documentation.formats.md(comments), documentation.formats.json(comments) ]); }) .then(function (results) { fs.writeFileSync(./docs/API.md, results[0]); fs.writeFileSync(./docs/API.json, results[1]); console.log(documentation generated); }) .catch(function (err) { console.error(err); process.exit(1); }); // 3. 独立做文档校验可用于 CI documentation.lint(index.js).then(function (output) { if (output) { console.error(output); process.exit(1); } });若要完全脱离文件系统例如在浏览器或纯内存场景运行可以像 docs/USAGE_NODE.md 的示例那样直接传入源码字符串var documentation require(documentation); var docs documentation.buildSync([{ source: /** hi this is a doc\nname myDoc */, file: direct.js }]); documentation.formats.md(docs, {}, function(err, res) { console.log(res); });这里buildSync直接接收{ source, file }对象作为入口source是待解析的 JSDoc 源码字符串file是逻辑文件名用于错误定位与链接推断。七、与 CLI 的对应关系Node API 的参数与 CLI 选项一一对应完整 CLI 帮助见 docs/USAGE.mdNode API 参数CLI 选项说明access--access, -a访问级别过滤CLI 默认包含public、protected、undefinedshallow--shallow关闭依赖解析external--external外部模块白名单inferPrivate--infer-private命名推断私有的正则extension--require-extension, --re/--parse-extension, --pe额外解析 / require 的扩展名sortOrder--sort-order排序方式source/alpha/kind/memberofhljs配置文件中的hljs键代码高亮配置如highlightAuto二者的核心区别在于CLI 是一次性面向终端用户的黑盒命令而 Node API 把解析与输出拆成可组合的 Promise 链便于嵌入构建系统、接入 CI 或做深度定制。八、延伸阅读docs/USAGE_NODE.mdNode 库使用的快速上手与buildSync内存输入示例docs/CONFIG.mddocumentation.yml配置toc排序、叙述性章节、file引用、children分组的完整说明src/index.jslint、build、formats的最终实现与导出src/parse.jsJSDoc 标签解析、同义词归一化与扁平化规则src/lint.jslint 规则类型命名规范化、参数推断比对src/output/markdown_ast.jsMarkdown AST 的章节组装逻辑tests/index.js 与tests/bin.jsNode API 与 CLI 的测试用例可作为行为契约参考。赞分享文档CLI【免费下载链接】documentation:book: documentation for modern JavaScript项目地址https://gitcode.com/gh_mirrors/do/documentation点击查看免费下载相关推荐documentation.js 完全指南现代 JavaScript 的 JSDoc 文档生成系统documentation.js 完全指南现代 JavaScript 的 JSDoc 文档生成系统 导读 documentation.js 仓库内以 doc文档CLIWSABuilds调试技巧ADB连接与Android应用日志分析实战WSABuilds调试技巧ADB连接与Android应用日志分析实战 WSABuilds是一款能让你在Windows 10和Windows 11电脑上运行An开发工具documentation.js 终极指南现代 JavaScript 文档生成的完整解决方案documentation.js 终极指南现代 JavaScript 文档生成的完整解决方案 documentation.js 是一个专为现代 JavaScr文档CLI上一篇Beads 与 Factory.ai Droid 集成指南通过 bd setup factory 托管 AGENTS.md 指引下一篇CookLikeHOC 肥肠鸡完整复刻指南从鸡块预处理到糊辣油淋面的出品全流程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考