npm 包 toolkit-jsdoc 使用教程

阅读时长 5 分钟读完

前言

在前端开发中，我们通常需要对代码进行注释以便于其他人理解和维护。同时，我们也需要生成文档来记录代码的用法和特性。而 JSDoc 就是专门用来生成 JavaScript 代码文档的工具。本文将介绍如何使用 npm 包 toolkit-jsdoc 来生成优美的 JavaScript 文档。

工具介绍

toolkit-jsdoc 是一个 JSDoc 的插件工具，它提供了多种方式来生成文档。包括生成 HTML 文档、生成 Markdown 文档、生成 JSON 文件等等。并且，它还能够自定义模板，以满足不同项目的需求。其中，基于 Markdown 的文档生成方式是 toolkit-jsdoc 的亮点。

安装

  1. 在命令行中进入你的项目目录。

  2. 运行以下命令进行安装：

    这里使用了 --save-dev 表示将工具安装到 devDependencies 中。

准备工作

在开始使用 toolkit-jsdoc 之前，我们需要为我们的项目添加一些 JSDoc 注释。例如下面这个例子：

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

这段代码中，有注释 计算两个数字的和，指明了这个函数的功能。其中，加了 @param 和 @returns 两种注释，可以指明参数和返回值的类型。这样，我们就可以使用 toolkit-jsdoc 来生成文档了。

使用方法

toolkit-jsdoc 有一个全局命令 jsdoc，我们可以使用它来生成文档。

  1. 在命令行中运行以下命令：

  2. 这里的 ./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 文件复制到新生成的文档目录中。

  3. 运行完命令之后，我们就可以在 ./docs 目录下看到生成的文档了。

自定义模板

如果我们需要自定义文档的样式和布局，或者需要添加一些个性化的内容，可以自己编写模板。

在 toolkit-jsdoc 中，模板是一个基于 EJS 的静态网页，我们可以根据自己的需求添加、修改和删除其中的元素和样式。

我们以修改样式为例，假设我们想要把所有函数名、变量名和类型都加粗：

  1. 找到 toolkit-jsdoc 的默认模板 ./node_modules/toolkit-jsdoc/jsdoc-template ，并复制到我们自己的项目中，例如 ./docs/jsdoc-template。

  2. 在 ./docs/jsdoc-template/static/css/jsdoc.css 中加入以下代码：

  3. 在命令行中运行以下命令：

    这里的 -t ./docs/jsdoc-template 表示我们指定了自定义模板。

  4. 使用浏览器打开 ./docs/index.html，就可以看到生成的文档了。可以看到，所有函数名、变量名和类型都已经被加粗了。

结语

本文介绍了如何使用 npm 包 toolkit-jsdoc 来生成 JavaScript 代码文档，并演示了如何自定义模板。在实际项目中，我们需要文档来记录代码并协同开发，而 toolkit-jsdoc 可以帮助我们生成美观、易读、易懂的文档，以提高开发效率和团队协作。

来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/the-toolkit-jsdoc

相关推荐
精选内容