[TOC] # 推薦參考 [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`格式來書寫，常用的關鍵詞有： <table> <thead> <tr> <th>關鍵詞</th> <th>描述</th> </tr> </thead> <tbody> <tr> <td><code>@auhor</code></td> <td>作者</td> </tr> <tr> <td><code>@param</code></td> <td>參數</td> </tr> <tr> <td><code>@example</code></td> <td>示例</td> </tr> <tr> <td><code>@link</code></td> <td>鏈接</td> </tr> <tr> <td><code>@namespace</code></td> <td>命名空間</td> </tr> <tr> <td><code>@requires</code></td> <td>依賴模塊</td> </tr> <tr> <td><code>@return</code></td> <td>返回值</td> </tr> <tr> <td><code>@version</code></td> <td>版本號</td> </tr> </tbody> </table> 其中，param關鍵詞的格式為： ``` /** * @param {String} 參數描述 */ ``` > 參考資料 YUI Compressor注釋規范：http://yui.github.io/yuidoc/syntax/ JSDOC：http://usejsdoc.org/ FED文章：http://frontenddev.org/article/sublime-does-text-3-plug-in-docblockr-with-javascript-comments-specification.html