在现代的前端开发中，我们经常需要使用各种各样的第三方库和插件来完成各种功能。而 npm 包 enlightme 就是一个非常实用的工具，它可以帮助我们更加方便地编写和管理代码注释。
在本文中，我们将详细介绍 npm 包 enlightme 的使用教程，不仅包含基本使用方法，还涵盖了一些高级技巧，希望能够对大家有所帮助。
什么是 enlightme？
enlightme 是一款基于 Markdown 的注释工具，它可以让我们更加方便地在项目中编写文档和注释，并且还能够自动生成对应的 API 文档。
使用 enlightme，我们可以通过一些简单的标记来描述代码中的函数、类、变量等，这些标记会被 enlightme 自动解析并转化为可读性更好、比较友好的 HTML 文档。
安装和基本使用
enlightme 是一个 npm 包，因此我们可以通过 npm 来安装它。具体来说，我们可以在终端中执行以下命令：
npm install --save enlightme
安装完成之后，我们就可以在代码中开始使用 enlightme 了。
在代码中使用 enlightme 的基本步骤如下所示：
- 在注释中使用 enlightme 的标记。
- 运行 enlightme 命令生成 HTML 文档。
- 打开 HTML 文档并查看结果。
下面让我们来看一个具体的例子。假设我们有一个 JavaScript 文件，里面包含一个名为 add 的函数。现在我们想要为这个函数添加一些注释。做法如下：
-- -------------------- ---- ------- --- - --------- - ------ -------- - ------ - ------ -------- - ------ - ------- -------- ------- -- -------- ------ -- - ------ - - -- -
在上面的注释中，我们使用了一些 enlightme 的标记，比如 @param、@return 等等。这些标记用于描述函数的输入和输出参数，它们是 enlightme 的核心标记之一。
注释完成之后，我们就可以在终端中使用 enlightme 命令来生成对应的 HTML 文档了。具体来说，我们可以在终端中执行以下命令：
npx enlightme --input=./add.js --output=./docs
上面的命令中，--input 和 --output 参数分别指定了源文件和输出文件的路径。执行完命令之后，我们会在 docs 目录中看到生成的 HTML 文件。如果一切顺利，我们就可以在浏览器中打开该文件，并查看对应的文档和注释了。
标准标记和额外标记
除了上面介绍的 @param、@return 等标记之外，enlightme 还支持一些额外的标记，比如 @deprecated、@example、@throws 等等，它们都可以用于更详细地描述函数的使用方法和注意事项。
下面列举一下 enlightme 支持的标准标记和额外标记：
标准标记
- @param：描述函数的输入参数。
- @return：描述函数的输出参数。
- @throws：描述函数可能抛出的异常。
额外标记
- @deprecated：标记该函数已废弃。
- @example：提供一个示例代码。
- @private：标记该函数为私有函数（不公开）。
- @todo：标记还未完成的功能。
- @ignore：标记某个函数或类不需要生成文档。
实用技巧
在使用 enlightme 的过程中，我们还可以利用一些实用技巧来提高我们的工作效率。
自定义主题
默认情况下，enlightme 生成的文档和注释都是按照一定的样式来呈现的。但是如果我们想要自定义文档的样式，我们可以通过自定义主题来实现。
具体来说，我们需要在项目中新建一个主题样式表，然后在 enlightme 命令中使用 --theme 参数来指定该样式表的路径。这样，生成的文档就会按照我们自定义的样式进行呈现了。
自动生成文档
如果我们的代码比较大，手动编写注释和文档可能需要花费很长时间。不过好在 enlightme 支持自动扫描源代码并自动生成文档的功能。
具体来说，我们可以在 enlightme 的命令中使用 --src 参数来指定需要扫描的源代码目录，同时使用 --output 参数来指定输出目录。这样，enlightme 就会自动扫描该目录下的所有代码，并生成对应的 HTML 文档。
下面是一个示例命令：
npx enlightme --src=./src --output=./docs
总结
通过本文的介绍，我们了解了 npm 包 enlightme 的基本用法和高级技巧，希望对大家有所帮助。enlightme 是一个非常实用的工具，可以帮助我们更加方便地编写和管理代码注释，同时还能够自动生成对应的 API 文档，这对于提高我们的开发效率和工作质量都是非常有帮助的。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/60066e25a563576b7b1ece94