前端开发有许多需要写文档的工作，比如 API 文档、组件文档、示例文档等等。jsdoc 是一款非常流行的 js 文档生成工具，可以很方便地为 js 代码生成文档，但 jsdoc 默认生成的文档不够美观，不够清晰。今天就来介绍一款 npm 包 daybrush-jsdoc-template，它可以让我们以更加美观、清晰的方式为 js 代码生成文档。
安装
首先我们需要在项目中安装 daybrush-jsdoc-template，可以通过 npm 进行安装。
npm install daybrush-jsdoc-template --save-dev
配置
安装成功后，我们需要在项目的根目录下新建一个 jsdoc.json 配置文件，并设置 daybrush-jsdoc-template 为文档生成器。
-- -------------------- ---- -------
-
--------- -
----------------- -------------------
----------------- ---------------
--
------- -
----------- -----------------------------------------
----------- -------
-------------- ----------
---------- ----
-
-注意这里的 template 配置项，它指定了 daybrush-jsdoc-template 作为文档生成器。在生成文档时，jsdoc 将会根据 daybrush-jsdoc-template 中定义的模板文件来生成文档。
使用
配置好后，我们就可以使用 jsdoc 命令来生成文档了。
npx jsdoc -c jsdoc.json
执行该命令后，在项目根目录下的 docs 目录下就会生成我们的文档了。
示例
下面来看一段示例代码及其文档。这段代码是一个实现拖拽和缩放功能的组件，我们先来看一下它的 jsdoc 注释。
-- -------------------- ---- -------
---
- ------ --------
- ---------- - ----- --- -------- --- --------- --------
- -------- ---------
--
----- -------- ------- --------- -
---
- ------ - ---------
-
- ----------- --------
- ------ ------------- ------- - --- ------- -- -- -------- --- ----------
- ------ -------- ------- - --- ------- --- --- ---------
- ------ -------- ----------------- - --- ----- -------
- ------ --------- ------------------------ - ------- --- --------- -- ----------
--
-------------------- -------- -
-------------- ---------
---------- - ------------- -- --
-------------- - ------
---------------- - ----------------------------
----------- - -----------------------
-------------- - --------------------------
-------------------------------------- ------------------
------------------------------------------ ------------------
-
---
- ----- --------
-
- --------
- ------ ------------ ----- - --- ------
- -------- ------
--
------------------ -
-- ---------------- -- --------------- -
-------
-
-------------- - -----
----- ---------- - -----------
----- ---------- - -------------
----- ----------- - ------- -- -
----- ----- - ------------- -- ---------------- -- -------------- - ---
---------- - ---------------------------- - ------ ----- ----
--------------
-----------------------
-
----- --------- - -- -- -
--------------------------------------------- -------------
------------------------------------------- -----------
---------------------------------------------- -----------
-------------- - ------
-----------------
-
------------------------------------------ -------------
---------------------------------------- -----------
------------------------------------------- -----------
-
---
- -----
-
- --------
- -------- ------
--
-------- -
----- ---------- - -------------
----- ------ - -----------
----- ------ - -----------
------------------------- --------
-
---
- --- --------
-
- --------
- -------- ------
--
----------- -
-- -- --------- ----- ------- ----
-
-上面的 jsdoc 注释使用了 @class、@classdesc、@extends、@constructs、@param 等标签来描述该组件的信息，包括组件的名称、描述、继承、构造函数、参数等等。
最后，我们通过 daybrush-jsdoc-template 生成的文档如下图所示，它美观、清晰，更加易读，为文档的使用者提供了方便。
总结
daybrush-jsdoc-template 是一款非常好用的文档生成器，它可以帮助我们生成更美观、清晰、易读的文档。使用 daybrush-jsdoc-template 能够为我们的项目带来诸多好处，比如提高文档的质量、方便团队成员查阅文档、提高代码的复用率等等。如果您也需要为自己的项目生成文档，不妨试试 daybrush-jsdoc-template。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/5ef85d3f403f2923b035b97f