# 推荐参考[JSDoc](http://usejsdoc.org/)
## 什么是JSDoc
JSDoc是一个根据javascript文件中注释信息，生成JavaScript应用程序或库、模块的API文档 的工具。你可以使用他记录如：命名空间，类，方法，方法参数等。类似JavaDoc和PHPDoc。现在很多编辑器或IDE中还可以通过JSDoc直接或使用插件生成智能提示。从而使开发者很容易了解整个类和其中的属性和方法，并且快速知道如何使用，从而提高开发效率，降低维护成本。
## 使用JSDoc
JSDoc本质是代码注释，所以使用起来非常方便，但是他有一定的格式和规则，只要了解这些，那么后面的事情，比如生产文档，生成智能提示都可以通过工具来完成。
## 注释规范
目前脚本、样式的注释格式都有一个已经成文的约定规范，最初是YUI Compressor制定。
~~~
/**
* 这里的注释内容【会】被压缩工具压缩
*/
/*！
* 这里的注释内容【不会】被压缩工具压缩
* 与上面一个注释块不同的是，第2个*换成了!
*/
~~~
其中说到这里说到的压缩工具有[YUI Compressor](http://yui.github.io/yuicompressor/)、[Google Closure Compiler](http://code.google.com/closure/compiler/)、[gulp-uglify](https://github.com/terinjokes/gulp-uglify)、[grunt-contrib-uglify](https://github.com/gruntjs/grunt-contrib-uglify)等，这些压缩工具都支持以上的压缩约定。常常把文件的关键信息放在第2种注释内容里，如文件名称、版本号、作者等。
关于这些关键信息，都由一些关键词和一定的格式来书写。关键词书写格式为：
使用`@key desc`格式来书写，常用的关键词有：
| 关键词 | 描述 |
| --- | --- |
| `@auhor` | 作者 |
| `@param` | 参数 |
| `@example` | 示例 |
| `@link` | 链接 |
| `@namespace` | 命名空间 |
| `@requires` | 依赖模块 |
| `@return` | 返回值 |
| `@version` | 版本号 |
其中，param关键词的格式为：
~~~
/**
* @param {String} 参数描述
*/
~~~
> 参考资料
> YUI Compressor注释规范：[http://yui.github.io/yuidoc/syntax/](http://yui.github.io/yuidoc/syntax/)
> JSDOC：[http://usejsdoc.org/](http://usejsdoc.org/)
> FED文章：[http://frontenddev.org/article/sublime-does-text-3-plug-in-docblockr-with-javascript-comments-specification.html](http://frontenddev.org/article/sublime-does-text-3-plug-in-docblockr-with-javascript-comments-specification.html)
