简介
在前端开发中，我们经常需要使用 TypeScript 来编写代码。而随着项目的增长，代码复杂性也随之增加，导致我们需要对代码进行更详尽的文档记录。而 TypeDoc 是一款使用 TypeScript 编写的文档生成工具，他能够帮助我们自动生成文档。同时，@jonrimmer/typedoc-plugin-external-module-name 这个 npm 包可以使我们生成的文档中，外部模块的名称可读性更好，有助于提高文档的阅读性。
安装
首先，在你的项目目录下，使用 npm 安装 TypeDoc：
npm install typedoc --save-dev
然后，安装 @jonrimmer/typedoc-plugin-external-module-name：
npm install @jonrimmer/typedoc-plugin-external-module-name --save-dev
配置
在项目的根目录下，新建一个名为 typedoc.json 的文件。这个文件是 TypeDoc 默认的配置文件。我们需要在这个文件中，指定使用 @jonrimmer/typedoc-plugin-external-module-name 这个插件。
-- -------------------- ---- -------
-
--------------------- -
-------------- -------------
-------------------- ---------------
--
--------- -
------------------------------------------------
-
-使用
完成配置之后，在项目根目录下执行以下命令即可生成文档：
npx typedoc
同时，在使用中，我们可以指定更多选项进行进一步的修改，如--out <folder>修改生成文档的输出路径，--mode <file|modules>指定生成文档中是否包括所有项目文件或只包括指定的模块等。
-- -------------------- ---- -------
-
--------------------- -
-------------- -------------
-------------------- ---------------
--
--------- -
------------------------------------------------
--
---------------
----------------
-示例代码
-- -------------------- ---- ------- --- - --------------------- - ------- ----------- -- --- - ---- ---------- --- ----- -- ----------- --------- -- - ---------- -- ---- -------------- - ----- ----- ------ - ------ ------- ---------------
{
"external-modulemap": {
"@my/project": "my-project"
},
"mode": "file"
}在生成的文档中，这段代码的描述将会是 "Enum describing the types of transitions available to a component." 而不再是 "@my/project.Enum Type describing the types of transitions available to a component." ，使得文档的可读性和易用性大大提高。
总结
通过使用 @jonrimmer/typedoc-plugin-external-module-name 这个 npm 包，我们可以使我们自动生成的文档中，外部模块名称更加可读，从而提高文档的阅读性和可用性。使用该插件，可以大大减轻因为代码复杂导致文档难以撰写的问题。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/6005601681e8991b448de2ea