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

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

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

这时候若是每一个人都对本身程序有一个文档化的阐释，即可对上述问题作出很大的缓解，一般程序的文档化需求只存在于大型项目或是拥有成熟体系的框架之中，对于前端们来说其实大多数时候都想用文档来展现和沉淀本身的知识成果的，可一直缺少一套行之有效快速一致性的解决方案，致使在你们谈到程序文档化的时候都由于时间关系，繁琐程度就望而却步了。

长期以来前端开发们都缺少一个像样的文档化工具，虽然在这以前出现过 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：在文档注释中标记某个类或类成员的锚点。

文档化你的项目不只可让催悲的前端们将本身写的注释变动具备价值，也能够为项目后期维护带来巨大便捷，在协同做战环境下起着相当重要的做用。