在前端开发中，我们经常需要添加注释来说明代码的作用和参数的含义。而在 JavaScript 中， JSDoc 是一种常用的注释格式。它不仅可以方便开发者书写文档，还可以通过一些工具自动生成文档。
在本文中，我们将介绍一个可以让我们将字符串转换为 JSDoc 注释的 npm 包——string-to-jsdoc-comment 的使用教程。
1. 安装
首先，在你的项目中打开终端，输入以下命令安装该包：
npm install string-to-jsdoc-comment
2. 使用
使用该包非常简单，只需要调用它的一个方法即可。该方法接受两个参数：字符串和一个可选的配置对象。它将返回一个字符串，其中包含了 JSDoc 格式的注释。
2.1 基本用法
下面是一个最基本的用法示例：
-- -------------------- ---- ------- ----- ------------- - ----------------------------------- ----- --- - -------------- - -------- - --------- ----- ------- - ------------------- --------------------- -- --- --- - ------------- - -------- - ------- --- --
如你所见，我们首先导入了该包，并定义了一个字符串。然后，我们调用了 stringToJsdoc 方法，将该字符串作为参数传递给它，并将返回的结果保存到 comment 变量中。最后，我们将 comment 打印到控制台上，它的输出结果就是包含了 JSDoc 格式的注释。
2.2 配置
stringToJsdoc 方法的第二个参数是一个可选的配置对象。它可以用来控制注释的样式以及缩进。下面是一个示例：
-- -------------------- ---- -------
----- ------------- - -----------------------------------
----- --- - ----------
----- ------- - ------------------ -
------- - -- -- ----- - ---
-------------- ----- -- ------------
---
---------------------
-- ---
---
- -------
---
--在上面的示例中，我们使用了两个配置属性：indent 和 asteriskSpace。其中，indent 控制注释的缩进值，我们将其设置为 4 个空格；而 asteriskSpace 用于决定注释中句号之后是否要增加空格。
3. 深入理解
理解本包的工作原理有助于我们更好地使用它。在这一节中，我们将深入了解它的实现方式。
3.1 正则表达式
本包的核心代码在于使用正则表达式。下面是该包使用的正则表达式：
const RE_SENTENCE = /([^\r\n.!?]*)(\r?\n|\r)?(?:(\.)|([!?]))?/g; const RE_WORDS = /[_a-zA-Z0-9]+/g;
其中，RE_SENTENCE 用于匹配注释中的句子。它由三个部分组成：
[^\r\n.!?]*：匹配任意非回车、换行、点、感叹号和问号的字符。(\r?\n|\r)?：匹配零个或一个回车、换行符。(?:(\.)|([!?]))?：匹配零个或一个点、感叹号或问号。
RE_WORDS 用于匹配句子中的单词。它只匹配由字母和数字组成的单词。
3.2 单词分类
本包的实现主要分为两个步骤。首先它会将字符串分成单独的单词。然后，它会将这些单词加入到已有的注释中，或者创建一个新的注释。
3.2.1 分词
为了将字符串分成单独的单词，该包使用了 RE_WORDS 正则表达式进行匹配：
const words = str.match(RE_WORDS) || [];
匹配结果被存储在 words 数组中。
3.2.2 加入注释
接下来，该包会遍历所有的单词。如果单词已经加入到注释中，那么它就会继续往下遍历；否则，它会处理这个单词，并将它加入到注释中。
对于每个单词，该包会检查它是否需要加入到已有的注释中。如果这个单词加入到注释中后，注释的长度不超过 80 个字符（不包括 * 和空格），那么它会被加入到已有的注释中：
if (wordInLine.length + word.length + 1 <= 80) {
wordInLine.push(word);
} else {
lines.push(wordInLine.join(' '));
wordInLine = [word];
}注释行的长度可以根据需要进行调整。
如果一个单词需要被多行注释包含，那么该包会自动在新行增加 * 和空格作为缩进：
const commentStr = lines
.map((line, i) => `${i === 0 ? ' ' : ' * '}${line}`)
.join('\n');3.3 使用规范
最后，我们需要提出一些使用规范，以使我们在使用该包时能够书写出良好的注释。
3.3.1 标点符号
好的注释应该是清晰、易读的。为了达到这个目的，我们应该在句子之后增加标点符号。也就是说，每个注释应该以句号，感叹号或问号结尾，除非它是一个短语或一个单词。
3.3.2 缩进
为了保持注释的整洁，我们应该使用恰当的缩进。要确保所有行的长度不超过 80 个字符，并使用 * 和空格进行缩进。
3.3.3 参数和返回值
如果我们的函数有参数和返回值，我们应该在注释中明确声明它们的类型和含义。例如：
-- -------------------- ---- -------
---
- ---------
- ------ -------- - - ------
- ------ -------- - - ------
- -------- -------- -------
--
-------- ------ -- -
------ - - --
-3.3.4 例子
我们还应该包含一些例子，以演示函数的使用方式，并展示它们的行为。这些例子应该与注释在同一文件中，并以 @example 标记开头。
-- -------------------- ---- -------
---
- ----------
- ------ -------- - - ------
- ------ -------- - - ------
- -------- -------- --------
- --------
-
- -- -- --
- ----------- ---
-
- -- -- -
- ----------- ---
--
-------- ----------- -- -
------ - - --
-4. 总结
本文介绍了一个可以将字符串转换为 JSDoc 注释的 npm 包——string-to-jsdoc-comment 的使用教程。我们详细讲解了该包的安装、基本用法和配置，并提供了示例代码。此外，我们还深入了解了该包的实现方式，并提出了使用规范，以帮助你编写高质量的注释。希望本文能够帮助你在前端开发中更好地实践文档化编程。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/the-string-to-jsdoc-comment