# 推薦參考[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)
