在前端开发中，我们通常需要编写注释来帮助自己和团队成员理解代码。但是一旦注释的数量变多，代码就会变得冗长且难以阅读，特别是当注释夹杂在代码中时，就会给代码阅读和维护带来困难。为了解决这个问题，我们可以使用 npm 包 es-comments 来管理我们的注释。
es-comments 是什么？
es-comments 是一个 npm 包，可以帮助我们在 JavaScript 中编写注释。与传统思维不同的是，它可以更方便地将注释提取出来并生成文档，让注释更易于阅读和维护。
安装
首先，我们需要安装 es-comments，可以使用 npm 来进行安装，安装命令如下：
npm install es-comments --save-dev
使用
使用 es-comments 非常简单，只需要在代码中使用一定的注释规则即可。
注释规则
JSDoc 风格注释
JSDoc 是一种类似于 JavaDoc 的注释风格，通过使用 JSDoc 可以很容易地生成文档等。
使用 JSDoc 风格注释时，我们需要使用 /** 开头，并在其后添加注释内容，最后使用 */ 结束。
举个例子：
-- -------------------- ---- ------- --- - -------- - ------ -------- - ----- - ------ -------- - ----- - -------- -------- ----- -- -------- ------ -- - ------ - - -- -
在上面的例子中，我们定义了一个函数 add，并为它添加了一条 JSDoc 风格的注释。这条注释描述了函数的作用、参数类型和返回值类型。
注释规则
es-comments 支持JSDoc 风格的注释以外，还支持一些简单的注释规则，具体规则如下：
- 行注释: 像 '// 这样' 这样的注释会被视为行注释。注释必须在代码行后面。可以使用
##注释符号为多个行注释放在一起。 - 段注释：位于一对注释标记之间的多行注释。注释标记可以是 /! ... / 或 / ... */。Math.js 将在 多年multi-line注释中构建（包括@subsection，@param等）。
<code></code>: 注释标记中的任何内容都会被忽略，除了用某种代码标记的部分。代码标记可以是<code></code>，<pre></pre>或<pre><code></code></pre>。
支持注释语法示例
-- -------------------- ---- ------- --- ------ ---- ------- --- ------ ---- ------- -- ------- -- ---- ------ ------ ---- ------- -- ------- -- ----- ----- ------- ------- ------ ---- ------- -- ------- -- ----- ----- ------- ------ ------ ---- ------- -- ------- -- ----- ----- ------- ------ ------ ---- ------- -- ------- -- ----- ----- ------- ----- ------ ---- ------- -- ------- -- ----- ----- ------- -- - --------- ------- -- --- - ----- ------- -- --- - ------- ----- --------- - ---- -------- ---- ---------- - ------ -------- ------ --------- ------------ -- -------- ------------------- - - --- - ---- ---- - ------ - - - ----- -- - ---- ------ ------ - - - ------- -- ----- -------- - - ----- -- ---- ------ ------ --
生成文档
当我们在代码中添加了一些注释之后，我们可以使用 es-comments 来生成文档。
在命令行中使用
我们可以通过命令行中使用 es-comments 来生成文档，并输出到控制台。运行命令：
npx es-comments [entryFilePath] [options]
其中，entryFilePath 是入口文件路径，options 是可选参数。
具体的，options 支持以下参数：
-o：指定输出文件路径。-t：指定模板文件路径。-e：指定需要排除的文件路径，可用,分隔。--all：指示是否包含所有文件，包括被忽略的文件。
使用配置文件
为了方便使用 es-comments，我们可以将配置写入配置文件中。我们可以在项目的根目录下新建 .escommentsrc.json 文件，然后将配置写入此文件中。
具体来说，.escommentsrc.json 支持以下配置项：
entry: 指定入口文件路径。output: 指定输出文件路径。template: 指定模板文件路径。exclude: 指定需要排除的文件路径，可用数组或逗号分隔。include: 指定包含的文件路径，可用数组或逗号分隔。ignore: 指定需要忽略的文件路径，可用数组或逗号分隔。
示例代码
为了更好地理解如何使用 es-comments，我们可以通过一个简单的示例来演示。
我们的项目结构如下：
-- -------------------- ---- ------- - --- -------- --- ---------- --- ---- - --- ------ - --- ----------- --- ------------------ --- -------------
index.js 文件内容如下：
-- -------------------- ---- -------
------ --- ---- ----------------
------ -------- ---- ---------------------
---
- ------
--
----- ---- -
---
- --------
-
- ------ -------- - -----
- ------ -------- - -----
- -------- -------- -----
--
------ -- -
------ ------ ---
-
---
- --------
-
- ------ -------- - -----
- ------ -------- - -----
- -------- -------- -----
--
----------- -- -
------ ----------- ---
-
-
------ ------- -----我们可以在对应的位置上添加注释，例如在 Math 类上方添加一行注释，如下所示：
-- -------------------- ---- -------
--- ---- -
------ --- ---- ----------------
------ -------- ---- ---------------------
---
- ------
--
----- ---- -
---
- --------
-
- ------ -------- - -----
- ------ -------- - -----
- -------- -------- -----
--
------ -- -
------ ------ ---
-
---
- --------
-
- ------ -------- - -----
- ------ -------- - -----
- -------- -------- -----
--
----------- -- -
------ ----------- ---
-
-
------ ------- -----接下来，我们在终端中执行以下命令：
npx es-comments index.js -o docs --template template.html
命令执行后，会在项目根目录下生成一个 docs 目录，其中包含我们生成的文档。
结论
在本文中，我们介绍了 npm 包 es-comments 的使用教程，它可以帮助我们更好地管理代码注释，并提取注释生成文档。我们在实际的项目中可以通过使用 es-comments 来让注释更有条理，提高前端代码的可读性以及维护性。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/600572ca81e8991b448e8f7e