JsDuck 使用指南（1）

标签：

团队合作开发javascript应用程序时，文档非常重要，但是以什么样规范编写文档、什么样的样式展现文档成为一个问题，目前javascript文档工具很多，有JsDoc、YUIdoc、JsDuck，笔者在对常见工具调研后，选择JsDuck,是因为：

1、JsDoc语法太过严格，稍微不符合解析规则就会导致不能正确生成文档

2、YUIdoc是支持多种语言的，这意味着你需要对于函数、类、命名空间等的名称和更多的内容进行显性的声明，这可能会造成文档和代码实现不一致的问题

3、JsDuck 语法解析更为灵活，样式美观，对于CommonJS、AMD和IIFE都能非常自然地生成文档

JsDuck是Sencha公司出品的开源js代码文档生成库，基于ruby编写。相信不少人都非常熟悉Extjs或sencha touch 的文档，也会时常感慨如此组织严密、样式精美的文档到底是怎么编写的，没错，它们都是按照指定规则在js代码上编写代码说明文档，然后由JsDuck生成的。

本序列分成两部分：1、JsDuck的基础配置 2、基于JsDuck生成文档所需的文档编写规范解析

git地址：https://github.com/senchalabs/jsduck

参考文档：https://github.com/senchalabs/jsduck/wiki

先配置好环境：

1、安装ruby环境

window需安装  rubyinstaller 1.9 下载地址 http://rubyinstaller.org/downloads/，安装完成后，确保ruby执行路径已经添加到您的环境变量中。

2、安装 Development

KitDevelopment Kit是一个在 Windows 上帮助简化安装及使用 Ruby C/C++ 扩展如 RDiscount 和 RedCloth 的工具箱，由于JsDuck依赖的组件对RDiscount、RedCloth有依赖，所以需要安装

3、使用gem命令安装 JsDuck

打开命令行，输入gem install jsduck,即可完成jsduck安装

到此,jsduck安装完毕，让我们来尝试一下jsduck：

在命名行输入 ： jsduck jsfilepath –output outputdirectory,其中jsfilepath 代表的是js文件路径，可以是js存放的文件夹的路径，这样的话，会把整个文件夹的js文件文档生成出来，也可以单独制定某个文件，outputdirectory 是文档的输出路径

假设现在 有文件 D:\jsduck\user.js 如下

/****
@class 定义user类
****/
function user(){
    this.age = 10;
}

生成的的文档截图，瞬间变得高大尚了：

在前端开发中，有很多人在使用grunt来作为前端构建工具，如果能把jsduck集成在grunt里，那就再完美不过了，好消息是已经有大神些了grunt-duck，duckduck

duck来做这个事，有兴趣的同学可以参照 https://github.com/dpashkevich/grunt-jsduck 来配置，在这里就不赘述了。

参考资料:

常见js文档工具对比：http://segmentfault.com/a/1190000002579067

jsdoc配置及使用：http://www.cnblogs.com/hxling/archive/2012/11/27/2791067.html

JsDuck 使用指南（1）

标签：

原文地址：http://www.cnblogs.com/zhoujiantao/p/4628839.html