论注释的重要性

好的注释,不仅能够让你的代码可读性更高,而且还能让你减少很多的工作量,比如能够根据注释,快速生成API文档。以下就是使用JSDoc快速生成API的方法。

首先安装JSDoc,安装命令如下:
npm install jsdoc –g

安装完成后,使用jsdoc –v 如果出现以下内容,说明安装成功

接下来,进入到项目目录下面,如果你的源代码放在根目录的src/目录下,那再根目录下新建conf.json文件,做为JSDoc的配置文件,并向里面添加以下内容:
[code lang=”js”]
{
“tags”: {
“allowUnknownTags”: true,
“dictionaries”: [“jsdoc”,”closure”]
},
“source”: {
“includePattern”: “.+\\.js(doc)?$”,
“excludePattern”: “(^|\\/|\\\\)_”
},
“plugins”: [],
“templates”: {
“cleverLinks”: false,
“monospaceLinks”: false
}
}
[/code]

用命令行打开根目录,使用以下命令即可生成API文档:
jsdoc src –r –c conf.json –d api

如果生成的API文档没有你代码里面相应的注释内容,说明注释内容不符合规范,具体规范可查阅JSDoc的API文档,http://www.css88.com/doc/jsdoc/
以下为vue的基本注释规范:

执行 jsdoc src –r –c conf.json –d api 即可生成对应的API文档,效果如下:

到此,你该知道良好的注释,是有多么的有用了吧?