npm 包 esdoc2-importpath-plugin 使用教程-JavaScript中文网-JavaScript教程资源分享门户

简介

在前端工程化开发过程中，文档编写是一个重要的环节，而 js 的文档编写，需要使用 jsdoc。然而，jsdoc 的生成后的文档，对 js 文件名长度有限制，导致在复杂的项目中不便于阅读。esdoc2-importpath-plugin 就是为了解决这个问题而产生的。

安装

可以通过 npm 来安装 esdoc2-importpath-plugin：

$ npm install esdoc2-importpath-plugin

使用方法

修改 esdoc 配置文件

在项目的根目录下创建 .esdoc.json 文件，内容如下：

{
  "source": "./src",
  "destination": "./docs",
  "plugins": [
    {"name": "esdoc-standard-plugin"},
    {"name": "esdoc2-importpath-plugin", "option": {"prefix": "src/"}}
  ]
}

其中，source 表示源代码的路径，destination 表示文档生成后的路径，plugins 数组中先添加 esdoc-standard-plugin（为 esdoc 的标准插件），再添加 esdoc2-importpath-plugin（自定义插件）。

配置参数

esdoc2-importpath-plugin 只有一个选项参数：prefix，用于指定源代码的路径前缀，以该前缀开始的路径会被保留。如果不添加该选项参数，会导致文档生成时路径带有绝对路径，而不是相对路径。

生成文档

使用以下命令可以生成文档：

$ npx esdoc

同时也可以在 package.json 中添加以下脚本：

{
  "scripts": {
    "docs": "esdoc"
  }
}

然后，使用以下命令可以生成文档：

$ npm run docs

示例代码

下面给出一个示例代码，以说明该插件的使用方法。

源代码

假设源代码目录结构如下：

src/
  components/
    Button.js
    Input.js
  utils/
    utils.js

Button.js 的内容如下：

-- -------------------- ---- -------
---
 - ------
 - ----- ------ ---------
 --
------ ------- ----- ------ -
  ---
   - ------------
   - ------ -------- ---- - --- ---- -- ------- -- --- ------
   --
  ----------------- -
    --------- - ----
  -
  
  ---
   - -------
   - ----- ----- -------
   --
  --------- -
    --------------------- ----------
  -
-

文档生成后

使用 esdoc2-importpath-plugin 生成文档后，目录结构如下：

docs/
  components/
    Button.html
    Input.html
  utils/
    utils.html

其中，生成的文档中的路径，前缀被去掉了。

结论

该插件使得文档的生成更加简单，使得在工程化项目中文档的编写更加方便，提高了团队协作的效率。

来源：JavaScript中文网，转载请注明来源 https://www.javascriptcn.com/post/600566b381e8991b448e2fb9