前言
在开发项目的过程中，我们可能需要生成文档来方便后续的使用和维护，而atomdoc-cli则是一款非常好用的npm包，它可以帮助我们生成我们的代码文档。本文将会详细地介绍如何使用atomdoc-cli这个npm包。
简介
Atomdoc-cli是一种基于注释文件的文档工具，可以读取JavaScript 代码中的注释并将其转换为Markdown格式，创建有条理的日志说明文档，方便我们对项目进行管理和修改，能够大大的提高我们的开发效率。
安装
Atomdoc-cli基于npm包构建，因此我们可以使用npm安装之：
npm install -g atomdoc-cli
使用atomdoc-cli
修改注释
使用atomdoc-cli之前，我们需要首先解释一下如何使用代码注释来生成文档。Atomdoc-cli需要代码注释来生成文档，注释应该包括一个简短的描述，和参数或返回值说明。注释的格式应该遵循JSDoc 风格，基本的注释格式如下所示：
/**
* 这是一个简单的函数。这个函数会接收一个字符串参数
* @param {string} str - 接收的参数
* @returns {string}
*/
function TestFunction(str) {
return str;
}上面的注释就是一个简单的函数的例子。Atomdoc-cli读取注释之后，会生成一个带有简要描述和参数/返回值的markdown文档。
生成文档
一旦修改完注释，我们就可以使用atomdoc-cli来生成我们的文档了。在命令行中输入如下命令：
atomdoc <source> <destination>
其中，source表示我们想要生成文档的源码文件的路径，而destination则是生成的文档文件的路径。例如：
atomdoc ./src/index.js ./docs/index.md
这个命令将生成一个名为“index.md”的markdown文件，并将该文件写入docs文件夹中。
指定生成文档的代码
在默认情况下，atomdoc-cli会搜索指定文件夹中的所有.js文件来生成文档。如果我们只想生成某个特定文件的文档，那么我们可以在生成文档时指定要生成文档的文件的文件路径，例如：
atomdoc ./src/file1.js ./docs/file1.md
这个命令将仅生成file1.js文件的文档。
修改主题
Atomdoc-cli默认使用mustache作为模板引擎，使用GitHub风格的主题。如果我们希望使用自己的模板和主题，那么我们可以通过使用--template和--theme选项来指定。
使用--theme选项来指定主题：
atomdoc --theme path/to/custom/theme <source> <destination>
使用--template选项来指定模板：
atomdoc --template path/to/custom/template <source> <destination>
列出可用的命令行选项
我们可以使用--help选项来列出可用的命令行选项：
atomdoc --help
示例
下面是一个完整的示例：
/**
* 这是一个简单的函数。这个函数会接收一个字符串参数
* @param {string} str - 接收的参数
* @returns {string}
*/
function TestFunction(str) {
return str;
}我们想要为这个函数生成一个文档，我们先修改函数的注释，然后使用atomdoc-cli命令生成文档：
atomdoc ./src/index.js ./docs/index.md
这将生成一个index.md的文件，其中包括我们在注释中指定的简短的描述和参数/返回值说明。
结论
Atomdoc-cli是一款非常有用的npm包，可以帮助我们快速、方便地生成代码文档。使用atomdoc-cli需要遵循注释的规则，以生成有条理的markdown文档。我们可以使用atomdoc-cli中提供的多种选项来自定义生成的文档。希望这篇文章能够帮助你快速上手atomdoc-cli并为你的项目生成精美的文档。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/5eedde25374d206107965c90