什么是 jsdoc-modified
jsdoc-modified 是一个基于 JSDoc 模板的 npm 包，能够帮助前端开发者快速生成详细的 API 文档。它提供了一系列的标签和注释方案，使开发者可以按照一定的规范来编写注释，从而自动生成文档。相比于手动编写 API 文档，使用 jsdoc-modified 可以省去很多繁琐的工作，大大提高开发效率。
安装
使用 npm 安装：
npm i jsdoc-modified
使用方法
配置文件
首先，需要在项目中创建一个配置文件，命名为 .jsdoc.json。该配置文件用于指定 API 文档输出的目录、JSDoc 模板、需要生成文档的文件等信息。
比如，我们创建一个名为 my-project 的项目，其目录结构如下：
- my-project
- dist
- node_modules
- src
- index.js
- .jsdoc.json
- package.json在 .jsdoc.json 中，可以指定一系列参数。以下是一个基本的示例：
-- -------------------- ---- -------
-
--------- -
---------- --------
---------- ----------------
--
------- -
----------- -------------------------------------
-------------- -------
--
------- -
------------------- ----
--
---------- ---
------------ -
------------- --- ---------
--------- ---
-------------- ------
----------------- ------
---------- -
-------------------- -----
-------------- -----
--
------- ---------------
-------- ---------
---------- -----------
----------- -----
------------- ----- -- ----- ------- --
-
-- source: 配置源代码路径，默认为项目根目录。
- opts: 配置生成的文档路径、JSDoc 模板路径等。
- tags: 配置允许使用的标签，allowUnknownTags 用于开启未知标签。
- plugins: 配置插件。
- templates：配置文档主题和风格。
编写注释
在 jsdoc-modified 中，注释是生成文档的关键。不同的注释标签可以用于描述不同的内容，比如函数返回值、函数参数、类属性等。以下是 jsdoc-modified 中常用的一些注释标签：
- @param - 指定函数参数
- @return - 指定函数返回值
- @see - 指定相关链接
- @description - 指定对象描述信息
- @example - 给出示例
比如，我们需要描述一个名为 add 的函数，该函数用于计算两个数的和。在函数定义上方添加注释，如下：
-- -------------------- ---- ------- --- - --------- - ------ -------- - - ------ - ------ -------- - - ------ - ------- -------- ----- - -------- - - ------ --- -- - -- -------- ------ -- - ------ - - -- -
自动生成文档
完成配置文件和注释的编写后，我们就可以使用 jsdoc-modified 自动生成文档了。在项目根目录下执行以下命令即可：
jsdoc -c .jsdoc.json src
其中，-c 参数指定配置文件路径，src 是指需要生成文档的文件路径。执行上述命令后，文档将生成在配置文件中指定的目标路径（如上文的 doc 目录）下。
总结
使用 jsdoc-modified 可以帮助前端开发者快速生成详细的 API 文档，提高开发效率。通过学习本文，你已经了解了 jsdoc-modified 的基本使用方法。接下来，你可以开始尝试在自己的项目中使用 jsdoc-modified 来生成文档，并按照指南编写详细的注释来使生成的文档更加清晰易懂。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/600672683660cf7123b3660a