前言
在前端开发中，我们通常需要对代码进行注释以便于其他人理解和维护。同时，我们也需要生成文档来记录代码的用法和特性。而 JSDoc 就是专门用来生成 JavaScript 代码文档的工具。本文将介绍如何使用 npm 包 toolkit-jsdoc 来生成优美的 JavaScript 文档。
工具介绍
toolkit-jsdoc 是一个 JSDoc 的插件工具，它提供了多种方式来生成文档。包括生成 HTML 文档、生成 Markdown 文档、生成 JSON 文件等等。并且，它还能够自定义模板，以满足不同项目的需求。其中，基于 Markdown 的文档生成方式是 toolkit-jsdoc 的亮点。
安装
在命令行中进入你的项目目录。
运行以下命令进行安装：
--- ------- ------------- ----------
这里使用了
--save-dev表示将工具安装到devDependencies中。
准备工作
在开始使用 toolkit-jsdoc 之前，我们需要为我们的项目添加一些 JSDoc 注释。例如下面这个例子：
--- - -------- - ------ -------- - - ----- - ------ -------- - - ----- - -------- -------- ------ -- -------- ------ -- - ------ - - -- -
这段代码中，有注释 计算两个数字的和，指明了这个函数的功能。其中，加了 @param 和 @returns 两种注释，可以指明参数和返回值的类型。这样，我们就可以使用 toolkit-jsdoc 来生成文档了。
使用方法
toolkit-jsdoc 有一个全局命令 jsdoc，我们可以使用它来生成文档。
在命令行中运行以下命令：
--- ----- -------- -- --------------------------------------------------------------------- -- ------------------------------------------- -- ------
这里的
./src/**表示我们的源代码目录，而-d ./docs表示生成的文档目录。其中，-c ./node_modules/toolkit-jsdoc/jsdoc-template/toolkit-jsdoc-config.json表示使用 toolkit-jsdoc 的配置文件，-t ./node_modules/toolkit-jsdoc/jsdoc-template表示使用 toolkit-jsdoc 的模板。如果我们需要生成 Markdown 文档，则需要在命令行中加上
-R README.md，表示生成文档之前将README.md文件复制到新生成的文档目录中。--- ----- -------- -- --------------------------------------------------------------------- -- ------------------------------------------- -- ------ -- ---------
运行完命令之后，我们就可以在
./docs目录下看到生成的文档了。
自定义模板
如果我们需要自定义文档的样式和布局，或者需要添加一些个性化的内容，可以自己编写模板。
在 toolkit-jsdoc 中，模板是一个基于 EJS 的静态网页，我们可以根据自己的需求添加、修改和删除其中的元素和样式。
我们以修改样式为例，假设我们想要把所有函数名、变量名和类型都加粗：
找到 toolkit-jsdoc 的默认模板
./node_modules/toolkit-jsdoc/jsdoc-template，并复制到我们自己的项目中，例如./docs/jsdoc-template。在
./docs/jsdoc-template/static/css/jsdoc.css中加入以下代码：-- - -- -- ---------- ---------- ---------- - ------------ ----- -
在命令行中运行以下命令：
--- ----- -------- -- --------------------------------------------------------------------- -- --------------------- -- ------
这里的
-t ./docs/jsdoc-template表示我们指定了自定义模板。使用浏览器打开
./docs/index.html，就可以看到生成的文档了。可以看到，所有函数名、变量名和类型都已经被加粗了。
结语
本文介绍了如何使用 npm 包 toolkit-jsdoc 来生成 JavaScript 代码文档，并演示了如何自定义模板。在实际项目中，我们需要文档来记录代码并协同开发，而 toolkit-jsdoc 可以帮助我们生成美观、易读、易懂的文档，以提高开发效率和团队协作。
来源：JavaScript中文网 ，转载请联系管理员！ 本文地址：https://www.javascriptcn.com/post/the-toolkit-jsdoc