用YUIDoc文档化JavaScript代码
转自i,unbug
什么是YUIDoc？YUIDoc会根据你写的代码注释生成API文档。
YUIDoc是个NodeJS应用，能将你的JS代码中的注释生成HTML格式的API文档。事实上，不仅是JS，任何支持块注释的语言都能使用。
要安装YUIDoc，首先要安装好NodeJS，然后使用 npm -g install yuidocjs 即可安装YUIDoc。通过命令 yuidoc <option> <path to js folder> 来使用。
一切都是关于标签
YUIDoc从源文件的多行注释中抽取到文档内容。当然，你会有些注释不想成为文档的一部分，让YUIDoc知道你的注释是非常重要的，必须以两个*开头。如下：
/** * YUIDoc 会认出这个 */ /* * YUIDoc 不会认这个 */
当然，注释里的内容才是最重要的。每个注释块都应该包含唯一的主标签，和零个或多个副标签。正确的标签加注释即可生成API文档。
主标签
开始讲主标签之前，必须明确一点，每个注释块中能切仅有一个主标签。描述了当前代码块的作用。
@module
@module标签描述了一组关联的类（JS中并不包含类，YUIDoc把构造器归纳成类）。如果我们用YUIDoc生成UDTWO的文档，那UDTWO对象就是个module，因为他同时管理Model、Collection、View和其他类。标签后面跟着写@module的名称：
/** * @module UDTWO */ var UDTWO = {};
@class
@class标签专门描述类的。在YUI库中通常是个构造函数。每个有@class标签的注释块都应该有一个@static或者@constructor的副标签。
/** * @class Model */ function Model(){ //... }
如果你的类是Model的一部分，那么不必在@class注释里指明与module的关系，只要文件的顶部有@module的注释即可。
@method
@method描述类的方法。你将会用到@return和@params副标签加以说明。
@property
@property标签说明类的属性值。@type和@default副标签配合使用。
@event
@event描述自定义的可触发事件。YUIDoc文档里指出：@event注释块近似于@method，但无需@return，@param则用于说明回调方法接受的参数。
副标签
注释块可以有多个副标签，通常同时有几个并且有些类型相同，下面介绍些比较常用的副标签：
@submodule
如果你的module分为多个（可能在同意文件中，可能不在），@submodule就因此而生：
/** * @module UDTWO * @submodule Array */ UDTWO.Array = {};
@extends
@extends描述类继承关系时非常有用，声明了当前累的超类是哪个：
/** * @class AppView * @extends UDTWO.View */ var AppView = UDTWO.View.extend({});
@constructor
如果一个类可被实例化，说明它得有个构造方法。如果你用的是原型链的方式，那类的构造也应该是构造方法。
/** * @class Point * @constructor * @param {Number} X * @param {Number} Y */ function Point(x, y){ this.x = x; this.y = y; }
@static
@static是描述那些不能实例化的静态类。一个最好的说明就是Math对象，你不必实例化才能调用其带的方法。是通过这个类本身来调用的：
/** * @class StringFilter * @static */ var StringFilter = {};
方法也可以静态化：可以实例化的类中，可能有些类级别的方法，这些方法被设计成静态的（只能被类调用）。
/** * @class Person * @constructor */ function Person(){ } /** * @method All * @static */ Person.All = function(){ };
@final
本标签描述属性和常量：值不可变。由于JS没有常量的概念，但编码的模式规范可能有这样的需求，那么这个标签就可以足以说明：
/** * @property DATE_FORMAT * @final */ var DATE_FORMAT = "%m %d, %Y";
@param
@param定义了@method（包括@constructor）或@event的参数。@param后写三个信息：name参数名，type参数类型（可选），description参数描述。这三个顺序可以为name type description或者type name description，参数类型必须用{}包括起来。
参数有可选项，放入[]中表示为可选参数，后接=someVal表明是默认参数（显然，只有可靠参数才会有默认值）。用*表示多个参数（name*表示1个或多个参数，[name]*表示0个或多个参数）。
/** * @class Point * @constructor * @param [x=0] {Number} 坐标点X坐标 * @param [y=0] {Number} 坐标点Y坐标 */ function Point(x, y){ this.x = x || 0; this.y = y || 0; }
@return
方法的返回值。@return后面要接type description。
@type
上面提到的主标签@property。你可以用@type标识其类型，如果类型为多个，则用“|”分隔。
@private / @protected
传统语言中都有private属性或者方法，不能在实例之外访问。与常量一样，JS里可以用@private / @protected来标识此项。
Protected属性或者方法是介于public和private之间的：它们只能被实例本身或者子类访问。
@requires
如果一个module依赖多个module，那么就用@requires来说明。
/** * @module UDTWO.Model * @requires UDTWO */
@requires用逗号分隔表明同时依赖多个。
@default
声明一个@property时用@default来定义它的默认值，须配合@type使用。
/** * @property element * @type String * @default "div" */ element: "div",
@uses
JS没有类，但是可以模拟子类，甚至于子类还是个混血儿（mixes）：设置从另一个类中“借”其属性和方法。这说的不是继承，因为你可以嵌套多个类。如果一个类“借”用了其他类，可以用@uses说明：
/** * @class UDTWO.Admin * @uses UDTWO.BLL * @uses UDTWO.DAL */ UDTWO.Admin = { mixes: [UDTWO.BLL, UDTWO.DAL], //... }
@example
想在代码中加入实例说明？那么就请用@example标签，后面缩进一级跟着写上实例，多少个实例无所谓。
@chainable
依照jQuery的链式风格，方法里面返回了当前对象，这样可以调用完一个方法后接着调用另一个方法，此时请用@chainable表明。
/** * @method addClass * @chainable */ jQuery.prototype.addClass = function(class){ //... return this; }
@deprecated
该标签表明代码不可再这么用，弃用的功能可能在今后的版本中更新或被移除，也可以在后边加些描述来说明为什么要这么做。
@since
该标签告诉读者自哪个版本起此代码被加入进来。
@beta
表示代码为测试版。
@extension / @extensionfor / @extension_for
该标签与@user相对。用它标明哪个类在其他类中能被嵌套，不是说此类总是被嵌套，而是说明可以被嵌套。
