ThinkSSL🔒 一键申购 5分钟快速签发 30天无理由退款 购买更放心 广告
[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