前言
在前端开发过程中,我们经常需要编写文档以方便他人理解我们所编写的代码。其中,TypeScript 是一个强类型的 JavaScript 超集,它提供了更为严格的类型定义并且更易于阅读。与此同时,TypeDoc 是一个在 TypeScript 代码上自动生成文档的工具,它可以让我们快速方便地生成文档并进行展示和分享。但是,有时我们需要对文档的格式和内容进行更加严格的规范和个性化设置,因而我们需要使用 Typedoc-Plugin-As-Member-Of 插件来实现此目的。
简介
Typedoc-Plugin-As-Member-Of 插件是一个 Typdeoc 自定义插件,它可以让我们对文档输出的格式和内容进行更为精细化的控制。它允许我们通过设置 “asMemberOf” 选项对类中嵌套的对象进行排版。通俗地说,在某些情况下,TypeDoc 的文档生成工具不会正确识别在类中嵌套的对象,而是将它们排在文档外部,导致文档的阅读难度增加。因此,Typedoc-Plugin-As-Member-Of 插件的出现可以让我们能更好地优化 TypeDoc 自动生成的文档。
安装和使用
使用 Typedoc-Plugin-As-Member-Of 插件十分简单,您只需要遵循以下步骤即可快速上手:
安装
在终端里,运行以下命令进行安装:
npm install typedoc-plugin-as-member-of --save-dev
使用
使用前,需要对 TypeScript 代码进行详细的注释。例如,在我们的代码中,有一个函数 foo:
/** * 生成一份食物 * @param type 食物类型 * @param count 生成数量 * @param properties 食物属性 */ function foo(type: string, count: number, properties: object) { ... }
假设我们想要在 TypeDoc 中将该函数按照类中的对象进行分组展示,我们只需要在需要分组的参数后面添加注释即可:
/** * 生成一份食物 * @param type 食物类型 * @param count 生成数量 * @param properties 食物属性 * @group food */ function foo(type: string, count: number, properties: object) { ... }
接着,配置 Typedoc-Plugin-As-Member-Of 插件的 asMemberOf 属性来达到 Grouping (分组)的效果:
npx typedoc --out docs --asMemberOf ./src/ --plugin typedoc-plugin-as-member-of --hideGenerator --name "My Library" ./src/index.ts
我们在 TypeDoc 中查看该函数时,可以看到将其按照“food”的参数进行了分组排版:
如果我们有多个参数需要分组展示,则只需要在对应的参数后面添加相同的 “@group [groupName]” 注释即可。
示例代码
-- -------------------- ---- ------- --- - --- -- ----- --- - --- - ------ - ------------ - ------ ---- ----- - ------ ----- ---- - ------ ---- ------ - ------ -------- ---- - ------ ----- -- ------------------ ----- ------- ------ ------ ------- ------ ----- ------- ------ --------- ------- -- --- - ---- - ------ ------- -- ------- -- --- - ---- - ------ ------- -- ------ -- -展开代码
总结
Typedoc-Plugin-As-Member-Of 插件可以让我们方便地优化我们的文档排版,提高阅读体验和文档的可读性。在项目中使用该插件非常简单,并且列举了以上示例供您参考,相信您可以在不久的将来使用其进行更为精细的中文化文档维护和更新。
来源:JavaScript中文网 ,转载请注明来源 https://www.javascriptcn.com/post/196800