/**
* # 描述
* 这是一个People类的描述
*
* **使用范例**：
*
*     @example
*     var p = new People({
*      age:2,
*      name:'name'
*     });
* @class People
*/

function People(cfg){}
People.prototype={
	/**
	* 事件触发描述
	* @event sleep
	* @param {Object} ev 事件参数的描述
	*/

	/**
	* 初始化配置年龄
	* @cfg {Number} age
	*/

	/**
	* 初始化配置名称
	* @cfg {String} name (required)
	*/

	/**
	* 获取它的性别
	* @type String
	*/
	sex:'male',

	/**
	* 获取它的名称
	* @return {String} 类型为字符串
	*/
	getName:function(){}
};

/**
* # 描述
* 这是一个Sub类的描述
* {@img img.png  alt text}
* @class Sub
* @extends People
*/
function Sub(cfg){}
Sub.prototype={
	/**
	* 事件的描述
	* @event eat
	* @param {Object} ev
	* 事件参数的描述
	*/

	/**
	* 配置项目描述
	* @cfg {Object} size 大小
	* @cfg {Number} size.height 初始化配置高度
	* @cfg {Number} size.width 初始化配置宽度
	*/

	/**
	* @inheritdoc People#sex
	* @type String
	*/
	sex:'female',

	/**
	* {@link People#getName getName方法}
	* 设置它的名称
	* @param {String} firstName 参数的描述
	* @param {String} lastName 参数的描述
	*/
	setName:function(firstName ,lastName){}
};

在windows命令行中输入：

另外还有一个–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：在文档注释中标记某个类或类成员的锚点。

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

本文来自：http://www.mymickey.org/?p=438

参考：https://github.com/senchalabs/jsduck#getting-it