【转】Jsduck一个纯净的前端文档生成神器

让前端程序更具可维护性，是一个老生常谈的问题，大多数时候我们都关注于应用层面的代码可维护性，如：OO、模块化、MVC，编码规范、可扩展和复用性，但这都是属于设计层面需要考虑的事情，可维护性还应包含另一个方面，也是很多coder容易忽略的地方，就是将自己写的程序以文档的形式沉淀起来，对自己工作有一个结构化的组织，也可以帮助到他人。

试想一下如下情况：
1、团队中加入了新的同学，这时他可能需要快速的将目前项目中现有程序有一个系统的了解，如：某个公共工具模块的用途，某个通用组件的接口，程序之间的依赖性，这时他只有去看源码和注释了。
2、团队中有同学离开，但他写的程序在此之前已经深入到项目的各个层面，最了解和能快速修改维护这些程序的人可能只有他，之后在迭代时遇上其环节，其他接手的同学只能望眼欲穿了。
3、自己写了一个不错的可复用组件，打算推广到团队中，这时他人需要使用自己的组件时不得不去看源码和注释了。

这时候如果每个人都对自己程序有一个文档化的阐释，便可对上述问题做出很大的缓解，通常程序的文档化需求只存在于大型项目或是拥有成熟体系的框架之中，对于前端们来讲其实大多数时候都想用文档来展示和沉淀自己的知识成果的，可一直缺乏一套行之有效快速一致性的解决方案，导致在大家谈到程序文档化的时候都因为时间关系，繁琐程度就望而却步了。

长期以来前端开发们都缺乏一个像样的文档化工具，虽然在这之前出现过 YUI DOC、JSDoc ，但这些工具始终难于将开发者从复杂的配置中解脱出来，从而使开发者很快便将它们遗忘。

如果有对sencha的 ExtJs 和 Sencha Touch 开发框架有过了解的同学想必都对为其定制的API文档印象深刻，富应用形态的展现方式和树节点的命名空间管理，避免了 YUI DOC 和 jQeury API 那样沉长页面带来的繁琐，而文档中附加的学习的范例也能帮助初学者尽快上手，生成这样强大的 API 文档使用的是jsduck，它不仅在使用和配置上非常简单，文档的 UI 和交互方式也是目前对于开发者来说是最友好的。

1. Jsduck 简介

jsduck 是 senchalabs 众多开源项目中的一个，它是使用 ruby 编写的 javascript API 文档生成器。

Jsduck强力功能点如下：

树形类命名空间组织
类子父关系的层次体系展示
成员与事件和配置项快速索引
可穿插着色代码范例演示和编辑范例代码
类成员源码实现部分快速导航
很简单一条命令可以将目录下的js生成帮助手册，推荐通过批处理文件操作

2. 安装jsduck

首先在Github（点击进入）上下载最新版的二进制版本（含多个平台版本），下载之后只有一个exe文件，此文件中已捆绑好了ruby解释器，不需要另外独立安装，将下载后的文件更名为jsduck.exe，在windows的环境变量的PATH变量中添加上此文件的路径，这样在命令行下输入jsduck便可可以直接调用到jsduck.exe。

注释规范需以“/**” 开头和“*/”结束，在 eclipse 或者 Aptana 这类支持 javaDoc 或 jsDoc 的 IDE 中键入 “/**” 按下回车键即可生成一个符合文档生标准的注释块，如果使用 SpketIDE，注释块生成的时候还能帮助开发者自动完成函数参数的命名。

以下是一些常用标签的注解：

@author：作者
@class：类
@deprecated：标记此方法属性或者类不赞成使用，在升级过渡的时候需兼容之前的API时特别有用。
@example：给类或者方法添加一个代码范例，jsduck不仅会给代码着色，还能给代码生成一个代码编辑器，编辑代码后可实时预览，使用@example需要四个空格的缩进。
@extends：标记一个类继承自另一个类，生成后会有一个类型继承体系陈列在文档视图的右侧。
@cfg：构造器的配置项，并在其后跟随“{className}”，再跟随参数名。
范例：@cfg {String} fieldName配置项的描述。
@return：与@cfg类似，标记一个函数成员调用过后的返回类型。
范例：@return {Number} 文字描述
@param：与@cfg类似，给一个函数成员标记其所需的参数类型和描述，如果参数类型为多种可以用“/”分割，如需要给参数进行更详细描述还能使用“[param.member]”描述符。
范例：@param {Number/String} fieldName
范例：@param {String[]} fieldName
范例： /**
* @cfg {Object} opt
* @cfg {Number} [opt.age]
* @cfg {Number} [opt.name=0]
*/
@event：标记一个事件，随后通常会跟随@param标签给事件回调函数声明参数的说明。
@inheritdoc：在其后跟随Class#member，常用在子类覆盖父类成员后，子类注释块还需继续使用父类注释的情况下使用。
@private：将成员标记成私有，虽然也有@public但如果不特殊标明即为公有。
@protected：将成员标记成受保护的。
@static:将成员标记成静态的，静态成员也会在文档中进行分类展示。
@img：在文档注释中链接一张图片，让文档变得更具可读性。
@link：在文档注释中标记某个类或类成员的锚点。

文档化你的项目不仅可以让催悲的前端们将自己写的注释变更具有价值，也可以为项目后期维护带来巨大便捷，在协同作战环境下起着至关重要的作用。