简介
better-docs 是一个简单易用的 npm 包，它可以帮助前端开发者更方便地生成项目文档。使用 better-docs 可以将你的项目中的注释转换为漂亮的文档页面，生成的文档页面包含了你的代码注释、函数签名、函数说明和代码示例等信息。
安装
你可以使用 npm 包管理器来安装 better-docs：
npm install better-docs --save-dev
使用
安装了 better-docs 包之后，我们就可以使用命令行来执行 better-docs 了。在命令行中使用如下命令：
better-docs [options] input.js
其中 options 参数用来设置一些选项，input.js 是你要生成文档的 JS 文件。
选项
better-docs 支持以下选项：
-o,--output: 指定输出的目录，默认目录为docs-t,--template: 指定文档模板，默认为内置的 ejs 模板-v,--verbose: 显示更多的信息
示例
假设我们有一个 JS 文件名为 calculator.js，其中有以下代码：
-- -------------------- ---- ------- --- - ---- - - ------ -------- - - --- - ------ -------- - - ---- - -------- -------- -- -- -------- ------ -- - ------ - - -- -
我们可以使用如下命令来生成文档：
better-docs calculator.js
执行命令后，会在当前目录下的 docs 目录中生成一个名为 calculator.html 的文档页面。在页面中，我们可以看到 add 函数的注释被转换为了函数说明和函数签名，并包含了注释中的参数和返回值类型等信息。
自定义模板
better-docs 内置了一个简单的 ejs 模板，但你也可以自己定义模板，以便更好地适应你的项目。在模板中，可以使用一系列模板变量来获取生成文档所需要的数据，例如：
<%= title %>: 用来显示页面标题<%= toc %>: 用来显示文档目录<%= content %>: 用来显示文档内容<%= code %>: 用来显示代码示例
下面是一个自定义模板的示例，该模板使用了 Bootstrap 框架：
-- -------------------- ---- -------
--------- -----
----- ----------
------
----- ----------------
---------- ----- ----------
----- ---------------- -------------------------------------------------------------------------------
-------
------
---- ------------------
------- ----- -------
---- ------------
---- -----------------
---- ------------- ---------------- ------------ ----------
-- -------------------- ---------------
------- ---------------------- ------------- ---------------------- ------------------------ ------------------------- --------------------- ------------------ ------------
----- -----------------------------------
---------
---- --------------- ---------------- ---------------
--- ---------- --------- -------------
--- --- --
-----
------
------
------
---- -----------------
---- -------------
---- ------------------
--- ------- --
------
------
------
------
---- -------------
---- --------------------
----
------
---- ------------------
--- ---- --
------
------
------
------- ----------------------------------------------------------------------
------- -----------------------------------------------------------------------------
------- -------------------------------------------------------------------------------------
-------
-------将上面的代码保存为 my-template.ejs 并指定 -t 选项使用即可。
总结
better-docs 是一个非常实用的文档生成工具，它可以帮助前端开发者更方便地生成项目文档，提高开发效率。本文介绍了如何使用 better-docs，并提供了自定义模板的示例，希望对大家有帮助。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/5eedad6ab5cbfe1ea0610c64