使用 gatsby-transformer-documentationjs 将 JSDoc 注释转换为可查询的 Gatsby 数据层【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsbygatsby-transformer-documentationjs是 Gatsby 生态中的 transformer 插件它借助 Documentation.js 从 JavaScript 源码中提取代码元数据当前支持 JSDocDocumentation.js 本身也支持 Flow可在此基础上扩展把注释变成结构化 GraphQL 节点。它被广泛用于 gatsbyjs.com 官网例如 https://www.gatsbyjs.com/docs/node-apis/ 一页即由该插件驱动。阅读本文后你将掌握该插件的安装配置、GraphQL 查询方式并理解其节点建模、描述字段 Markdown 化、示例高亮与类型定义链接等底层实现从而为自己的组件库或 API 代码搭建一套自动化的在线文档站点。插件定位与工作原理在 Gatsby 的数据管道中transformer 插件负责把 source 插件如gatsby-source-filesystem拉取到的原始文件节点转换成更丰富、可查询的数据节点。gatsby-transformer-documentationjs扮演的正是这一角色gatsby-source-filesystem把源码文件注册为File节点插件在onCreateNode钩子中识别 JS/JSX/TS/TSX 文件调用documentation.build(node.absolutePath, { shallow: true })解析出 JSDoc 元数据src/gatsby-node.js解析结果被逐条转换为DocumentationJs节点并通过createParentChildLink与源File节点建立父子关系src/gatsby-node.js最终你可以在 GraphQL 中像查询普通内容节点一样查询这些文档数据。插件当前版本为 7.17.0-next.0依赖documentation ^13.2.5与prismjs ^1.29.0peerDependencies 声明了gatsby ^5.0.0-next见 package.json。安装与配置安装插件npm install gatsby-transformer-documentationjs添加插件到 gatsby-config.js最简配置只需一行plugins: [gatsby-transformer-documentationjs]配置源码目录由于 transformer 只处理 source 插件产出File节点因此必须确保有一个指向源码目录的gatsby-source-filesystem实例plugins: [ gatsby-transformer-documentationjs, { resolve: gatsby-source-filesystem, options: { name: source, path: ${__dirname}/../src/, }, }, ]从源码看shouldOnCreateNode只对满足以下条件的File节点放行internal.mediaType application/javascript或扩展名为jsx、tsx、tssrc/gatsby-node.js。对应地测试中也专门验证了“仅处理 JavaScript File 节点”非 JS 媒体类型不会产出任何节点见 src/tests/gatsby-node.js。一个值得注意的健壮性设计onCreateNode调用documentation.build时包裹了 try/catch解析失败会被静默忽略src/gatsby-node.js源码注释说明了原因“Ignore as therell probably be other tooling already checking for errors and an error here kills Gatsby.”——即语法/解析错误通常已有其他工具链负责提示若在此抛错反而会拖垮整个 Gatsby 构建。编写 JSDoc 注释为了让插件提取到有用的内容源码中需要规范书写 JSDoc。以仓库测试夹具 code.js 为例/** * A pretty cool jsdoc example * param {string} paramName A nice crispy apple * example * const apple require(apple) * apple() */ exports.apple paramName { console.log(hi) }要点如下param {type} name description声明参数名、类型与说明会被解析成params子节点example块内代码会成为examples数组中的一项插件会将其原始文本保存为raw并用 Prism 按 JavaScript 语法高亮生成highlightedexample caption标题/caption可附带 caption从源码看caption 是从caption/元素的文本子节点中提取的src/gatsby-node.jscallback、typedef、property声明类型别名与对象结构会被建模为typedef节点并支持嵌套propertiesreturns、throws、deprecated、todos、yields、augments、implements等标签同样被支持完整字段见下文 Schema。更复杂的用法参考 complex-example.js其中演示了typedef {Object} ObjectType、嵌套property {string} nested.foo、可选属性property {number} [nested.optional]、callback CallbackType以及联合类型type {(ObjectType|Object)}的写法。测试对这类场景的断言src/tests/gatsby-node.js包括typedef 会生成顶层节点其properties___NODE指向属性子节点解构式的嵌套属性名会被“去前缀”nested.foo最终归一为foo源码中通过name.split(.)取最后一段实现见 src/gatsby-node.js可选类型[nested.optional]会被展开为optional: true并保留其真实类型number对应 src/gatsby-node.js 中对OptionalType的 unwrap 逻辑。此外夹具 jsdoc-and-flow.js 展示了 JSDoc 与 Flow 类型标注混用的情况Documentation.js 会把二者合并requiredParam: string与optionalParam?: number会产出与纯 JSDoc 完全一致的数据形状optional: false/optional: true。GraphQL 查询示例插件注册的根查询类型为DocumentationJs与allDocumentationJs。官方 README 给出的查询如下{ allDocumentationJs { edges { node { name description { childMarkdownRemark { html } } returns { title } examples { raw highlighted } params { name type { name } description { childMarkdownRemark { html } } } } } } }这段查询展示了插件最核心的数据形态name被注释符号函数、类、变量等的名称description注释中的描述文本。注意它不是一个字符串而是一个DocumentationJSComponentDescription节点——插件在createSchemaCustomization中为其声明了mimeTypes(types: [text/markdown])src/gatsby-node.js并且每个描述节点都以mediaType: text/markdown创建src/gatsby-node.js因此可以被gatsby-transformer-remark等 Markdown transformer 继续接管从而支持childMarkdownRemark { html }这类嵌套查询——这正是把注释渲染成富文本 HTML 的关键链路returns、params返回值与参数的子节点可进一步查询type.name、嵌套descriptionexamples示例代码数组raw为原始文本highlighted为 Prism 高亮后的 HTML。数据模型完整的 DocumentationJs Schema插件通过createSchemaCustomization显式声明了完整的节点类型src/gatsby-node.js了解这份 Schema 有助于写出更深层的查询标量字段name、kind、memberof、scope、access、optional、readonly、abstract、generator、async、override、hideconstructor、alias、copyright、author、license、since、lends、defaultJSON。描述类字段description、deprecated均指向DocumentationJSComponentDescription节点内部通过description___NODE链接。子节点数组通过___NODE关联augments、implements、params、properties、returns、throws、todos、yields。在onCreateNode中这些字段被逐一递归处理src/gatsby-node.js每个子项都成为独立的DocumentationJs子节点形成多级嵌套树并记录path与level以维护层级。成员分组members为DocumentationJsMembers类型包含static、instance、events、global、inner五组src/gatsby-node.js 与 src/gatsby-node.js。示例examples为DocumentationJsExample[]含caption、description、highlighted、raw四个字段src/gatsby-node.js。位置信息codeLocationDocumenationJSLocationRange与docsLocationDocumenationJSLocationRange各含start/endline、column分别对应代码位置与注释位置。源码中特意将 Documentation.js 返回的SourceLocation类实例通过JSON.parse(JSON.stringify(...))序列化为普通对象因为 Gatsby 在推断 Schema 时暂不支持类实例src/gatsby-node.js。测试断言apple的docsLocation为 1~7 行、codeLocation为 8~10 行与实际夹具文件完全吻合src/tests/gatsby-node.js。类型系统type为DoctrineType由 DoctrineDocumentation.js 的类型解析引擎产出含type如NameExpression、UnionType、TypeApplication、OptionalType、name、elements、expression、applications、params、fields、result等字段。类型定义链接typeDef把类型引用解析成节点Schema 中最巧妙的设计是DoctrineType.typeDef当一个类型的name指向文件中已有的typedef/interface/constant定义时插件会在类型对象上写入typeDef___NODE指向对应的DocumentationJs节点。节点构建阶段getNodeIDForType通过名称在解析结果中查找kind为interface、typedef、constant的文档项并递归遍历类型的applications、expression、elements字段注入引用src/gatsby-node.js。同时它检测循环引用若某个 typedef 自引用会通过helpers.reporter.warn发出警告而不是死循环查询阶段createResolvers为DocumentationJs.type注册了一个自定义 resolver沿着typeDef___NODE用context.nodeModel.getNodeById递归解析出真实的typeDef节点src/gatsby-node.js。测试夹具 complex-example.js 中的type {(ObjectType|Object)}正是利用了这一能力快照显示联合类型中ObjectType元素带有typeDef___NODE而内置的Object则为null见 src/tests/snapshots/gatsby-node.js.snap。在 GraphQL 中你可以沿着type.typeDef继续查询类型定义的描述与属性实现“类型 → 定义”的交叉引用导航。典型应用从注释生成 API 文档页结合以上能力一个典型的自动化文档站点工作流是用gatsby-source-filesystem指向要文档化的源码目录启用gatsby-transformer-documentationjs提取所有 JSDoc配合gatsby-transformer-remark将description/deprecated的 Markdown 渲染为 HTML在页面组件中查询allDocumentationJs遍历函数、参数、返回值、示例把examples.highlighted直接以 HTML 插入Prism 已生成带 token class 的高亮片段利用typeDef与members实现类型与成员之间的互相跳转。这种模式把“写文档”重新收敛回“写注释”源码与文档永远同源正是 gatsbyjs.com 的 node-apis 等页面所采用的做法。小结gatsby-transformer-documentationjs的核心价值在于用一套成熟的 JSDoc 生态Documentation.js Doctrine Prism打通“源码注释 → Gatsby 数据层 → 渲染页面”的完整链路。从 src/gatsby-node.js 的 490 余行实现可以看到它在细节上做了大量工程化处理——描述字段独立成 Markdown 节点、示例自动高亮、可选类型展开、嵌套属性去前缀、typedef 跨字段链接、循环引用保护等。若想进一步探索可以直接阅读插件的 README、实现源码 与 测试用例夹具目录src/__tests__/fixtures/下的示例代码也是快速上手 JSDoc 写法的绝佳参考。【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考