Jsduck:前端文档生成利器

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

 

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

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

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

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

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

Jsduck功能点如下：

1、树形类命名空间组织；

2、类子父关系的层次体系展示；

3、成员与事件和配置项快速索引；

4、可穿插着色代码范例演示和编辑范例代码；

5、类成员源码实现部分快速导航；

在Windows下安装jsduck：

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

使用jsduck ，在windows命令行中输入：

 

jsduck –builtin-classes sencha\senchalabs\jsfile\ –output=sencha\senchalabs\doc\ –encoding=gbk –images= sencha\senchalabs\images

如果不出意外你将在输出的目录中看到生成的文件了，目录中有一个index.html文件这便是文档的入口，在你的浏览器中打开它。

命令中“–”开头的为命令的参数，以下是一些常用的命令

 

–builtin-classes：构建javascript语言内建类文档，如Array或Object类的使用说明。
–output：文档输出所在目录。
–encoding：编码默认为utf-8，如果js文件中包含了中文字符设置gbk即可。
–welcome:为一个html文件的路径，文件中的内容会被解析出来放到文档的欢迎页显示。
–eg-iframe：配置一个html文件路径，这个html文件用来配置@example范例的预览方式，如需要生成非ExtJs或者sencha touch项目的话通常都需要自定义配置。
–images：如果文档中引入了图片需配置一个图片目录。
–title：自定义文档的标题
–footer：自定义文档脚注
–help：full 显示帮助文档。

    另外还有一个–config参数用来配置文档生成的命令集合，它的值是一个json配置文件的路径。

    创建一个config.json文件

{
	"–output":"sencha/senchalabs/doc/",
	"–encoding":"gbk",
	"–":["sencha/senchalabs/jsfile/"],
	"–eg-iframe":"sencha/senchalabs/eg-iframe.html",
	"–welcome":"sencha/senchalabs/welcome.html",
	"–images":"sencha/senchalabs/images"
}

    在命令行中输入

 

jsduck –builtin-classes –config=config.json

  实现的效果和第一个例子中是一样的，不过使用config.json的方式更加容易维护。

 

稍加留意会发现实际上文档的生成方式完全是基于文件中注释里面的 @tag 标签的，和 jsdoc 使用的标签规范是一样的。

  注释规范需以“/**” 开头和“*/”结束，在 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：在文档注释中标记某个类或类成员的锚点。

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

 

评论

1 楼 wangyudong 2017-11-27  

很多API doc生成工具生成API文档需要引入第三方依赖，重度依赖在代码里加注解的方式，并且不支持自动化测试RESTful API。

之前习惯用一款名字为 WisdomTool REST Client，它能够基于测试过的历史记录自动生成精美的RESTful API文档。完全不用引入第三方依赖，不用在代码里添加任何注解。完全跟API代码脱离，任何用户即使不了解API代码，也能够使用WisdomTool REST Client生成API文档。并且支持自动化测试RESTful API，输出精美的测试报告。
轻量级的工具，功能却很精悍哦！

https://github.com/wisdomtool/rest-client

Most of API doc tools do not support automated testing.

Once used a tool called WisdomTool REST Client supports automatically generating exquisite RESTful API documentation based on history testing cases without adding annotations to the code, it also supports automated testing, and outputs exquisite report.

Lightweight tool with very powerful features!

https://github.com/wisdomtool/rest-client