NodeJs 生成API文档

JSDoc是一个根据Javascript文件中的代码注释,生成API文档的工具。

简单使用

JSDoc注释放置在方法或函数声明之前,它必须以/ **开始,其他以/*/***或者超过3个星号的注释,都将被JSDoc解析器忽略。例如一下代码:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
/**
* Student类,学生.
* @constructor
* @param {string} name - 学生姓名.
* @param {string} address - 学生家庭住址.
*/
function Student(name, address) {
this.name = name;
this.address = address;
}
Student.prototype={
/**
* 获取学生的住址
* @returns {string|*}
*/
getAddress: function(){
return this.address;
}
};

上面的代码中,以@开头的是 JSDoc 的。因为JSDoc考虑向后兼容,所以一些注释标签存在别名。 比如@param有两个别名:@arg@argument

标签

关于标签参考:

生成Markdown文档

安装依赖

1
npm install -g jsdoc-to-markdown

使用

docs.sh文件:

1
2
3
4
5
6
PROJECT_ROOT="$PWD"
MARKDOWN_DOCS_DIR="${PROJECT_ROOT}/docs"
node_modules/.bin/jsdoc2md \
--files "lib/**/*.js" \
> "${MARKDOWN_DOCS_DIR}/api_docs.md"

运行docs.sh会在当前目录下的docs目录生成api_docs.md文件。

查看命令帮助:

1
jsdoc2md --help