YUIDoc语法参考

原文：http://yui.github.com/yuidoc/syntax/index.html

概述：

YUIDoc的语法对于使用过Javadoc, JSDoc, Doxygen或者其他文档生成工具的人来说应该非常熟悉。YUIDoc依赖诸如@param 或 @return等这类嵌入在注释模块中的标签,
它们以"/** "开始，并且以" */"结束。注释模块包含一些少量的标签来指明文档的特征，而大多数的标签在任何面向对象的语言里是通用的。


重要提示：YUIDoc 只解析 YUIdoc的注释块，不解析源代码。所以YUIDoc 使用起来相对简单并且与编程语言无关。然而，这也意味着你必须对YUIDoc的一切显式地声明清楚。
一个代码块只有你描述它是一个“method”或“class”,它才会被解析成一个“method”或“class”.另外一个重要的结论是：YUIDOC总会生成文档，因为没有注释模块的API成员会放在根目录下。

基本需求：
一个存在的注释块必须包含有且只有一个主标签(primary tag)，例如 @class 或 @method等。
还可搭配任意数量的副标签（secondary tag）例如： @param, @type, @extends等。一些副标签（secondary tag）可以用于任何注释块，而有一些副标签（secondary tag）
必须和特定的主标签(primary tag)一起使用才有意义。


一个源码树必须包含至少一个包含 “@module”标签的注释块。
每个模块（ module）必须至少有一个含有“@class”标签的注释块。
每个类（class）可以有任意数量的注释块，每个注释块可以包含一个@attribute, @class, @event, @method, or @property 标签。


主标签：
每个注释块必须包含有且只有一个以下标签:
module：
module表明这个模块包含一组相关的类（classes）。例如：YUI的app模块包含几个类（classes）,如，App.Base,Model,andRouter。
你可以选择性地把模块分成几个子模块（submodules）。


YUIDoc 要求你在每一个源码树（source tree）提供至少一个module.尽管通常在一个js文件中没有一个很明显的地方给你插入模块文档，
但是惯例是将模块文档插入到包含模块的主类或基类的顶层文件里。


main:
当YUIDoc 解析一个模块的目录时，可能有几个文件在这个目录下， 这些文件提供模块以及子模块的文档。YUIDoc会尝试判断那个模块包含了模块的主要描述。
如果在尝试判断过程中遇到麻烦，你可以增加一个"@main"标签在模块或子模块("module/submodule")中,这样YUIDoc就会该注释块的描述用作模块的描述，
并将描述显示在模块api的入口页。




class：
class表示该代码快是一个类。在js中，通常是一个构造函数生成一个对象。"@class"的值应该是一个字符串，用来说明是一个关于父对象的功能类。如:将"class"用于
 "Y.DD.Drag"的话，"@class"的值就是Drag,(并且它的命名空间@namespace就是DD).
 YUIDoc要求 methods, properties, attributes, and events属于一个类，因此通常你必须提供至少一个类在你源码树的模块里。"@class"应该存在于一个类构造器函数上边，
并且上述的 methods, events, properties, and attributes包含在类中。


"@class"应该与 "@constructor"或"@static"成对存在。




method:
method表示一个代码块是当前class的一个方法。默认，当前类是YUIDoc解析的最近的类，但是你可以通过"@for“来重新设定。
"@method"通常放在一个定义的方法上边。至少，你应该列出所有参数（@param）和返回的值（@return）。




event:
event表示当前代码块是一个自定义事件，类能够在自己感兴趣的某一执行代码时刻触发它。一个"@event"块在一定程度上与"@method"块相似，
但是不相同的地方有："@event"块与"@return"毫不相干，"@event"中的"@param"通常来描述一个挂在事件对象上的一个属性，事件对象方便回调监听对事件的接受。


理想情况是，应该是在定义事件的上方，即使代码仅仅是字符串的声明。如果你发现你的"@event"快找不到依靠，你至少应该将其放在所属类的下边，和其他能够
被类出发的事件组织在一起。




property:
property表示该代码快是当前类的一个属性。和方法一样，@property也应该放在属性声明的上方。至少你应该列出属性的”@type“信息，即使值是任意的或是混杂的。




attrbute：
[YUI-specific]表示该代码块是一个管理配置属性。一个属性是有一个对象创建的，并且被 YUI attribute API管理。它是一种超级属性，带有“setter”,"getter"，还有其他
一些好玩的特性，其中包括能自动触发变换事件。


"@attribute"应该直接放在定义属性的上边，不管是它在一个"Y.Base"对象的“ATTRS”(property)内还是其他什么地方。注意如果你在“yuidoc.json”文件里设置“attributesEmit”
为"true",那么YUI将会为属性变化事件自动生成文档，在整个源码树内，但不要你再写额外的注释。




副标签：
submodule：
指定这个模块（module）事实上是某一模块的子模块。例如，”app-transitions“是大模块”app“的子模块。
在YUI里，子模块是你能够以更好的丽都去加载模块。例如，“foo”模块可能有更小的“foo-core”或“foo-base“提供基础功能的子模块，再增加额外的子模块”foo-*“，可以增加
其他可选的特性。使用 YUI Loading,你能够选择性地去加载”foo-core“，或者”foo-core“和其他几个额外模块，或整个foo”rollup"。


namespace:
指定一个类的命名空间。"@namespace“注释块不应该包括”root“或”global“，这样的整个库挂载的对象。例如：”Y.DD.Drag“的”Drag”包含“@class”，那么"DD"的”@namespace“应该是“DD”,
而不是“Y.DD”。


提供一个“@namespace”使你能够在引用到在YUIDoc里相同名字的类，


extends:
表示一个类继承父类的成员，可能使用了 “Y.extend()”,“ Y.Base.create()”或相同的方法。YUIDoc 将会为从父类继承来的methods, properties, events, and attributes
生成api文档，并且回链到父类的文档。默认情况下的YUIDoc 主题，使用者可以决定是否显示继承来的成员。


config:
[YUI-specific]config是@attribute"别名。在YUI久的版本里，"@config"与"@attibute"承担的事稍微不一样，不过这2个概念已经合并了，在现在的YUIDoc里应该用"@attribute"来代替。


constructor:
表示该类可以被实例化(你可以这样调用使用：var foo = new Foo();)一个"@class"标签应该可以和"@constructor"或" @static tag"成对存在。


static:
标明该方法或者类是静态的。
对与方法来说，改方法可以被没有实例化过的类调用。
对于类来说，你不可以通过new()来实例化。你可以调用该类里的任何方法。


final:
标明属性是一个常量，不能被改变。


readonly:
[YUI-specific]表明这个attribute是由只读的property配置的，不能功过调用"set()“来改变，只读属性应该始终是其在文档中的默认值。
有时，使用properties,相当于”@final“.


writeonce:
[YUI-specific]表明该attribute是由"writeOnce"的property配置的，所以只能设置一次，要么通过应用"@default“,要么通过在构造器中设置，要么通过调用"set()"方法。


optional:
[YUI-specific]表明在使用class时，该attribute不一定要完全提供。


*param：
给一个普通函数(@method)，或一个构造器函数(@constructor)(通常在定义在一个"@block"的模块里)，或一个存在事件对象内property定义一个参数。可以在以下形式中选一个：


    @param {type} name description
    @param name {type} description
"{type}"是可选的，但是如果你包含了它，你必须用大括号抱起来，这样YUIDoc就能区分它和它的名字。名字可选语法：


    [name] — optional parameter
    [name=foo] — default value is foo
    name* — placeholder for 1..n args
    [name]* — placeholder for 0..n args
正如例子所显示的，你可以嵌套"@param"标签，这使你能够以他们自己特有的嵌套结构去文档化对象参数。


return:
表明一个方法返回的值，"@return"标签有特定的结构，形如：@return {type} Description. {type}是可选的。


for:
设置一个 YUIDoc 类的作用域。
使用"@for OuterClass"在一个有"@class"的注释块里，这样可以创建一个内部类，YUIDoc将会把接下来属于内部类的方法或者其他项生成文档，但是内部类显示属于外部父类。


为了关闭一个内部类，可以再添加"@for OuterClass"到内部最后的 @attribute, @event, @method, or @property的注释块里，这样就可以重新设置YUIDco解析器用外部类
来作为随后选项的所有者。


如果你不在内部类内，在一个 @attribute, @event, @method, or @property 注释块中使用"@for FarawayClass"，可以将这些和所有接下来的单个项都附加到指定的类里。
当你有个模块(module)的方法附加到一个类的原型对象里，但这个类却有是定义在某一个不同的完整文件里时，这个非常有用。


type:
指定property或attribute的类型。你可以指定一个类型，或者一个合法类型的列表，列表被竖线分割，如果你比较懒，也可以用其他任何或混杂的字符来分割。


private:
指定一个成员不能在外部访问。尽管YUIDoc不会为@private的注释块生成文档，但是对于内部的源代码来说，那些注释块还是相当漂亮、结构化的方式。所有的method和
property被认为是公有的，除非你显式标出他们是私有的或者被保护的。


protected：
表示成员不应该被调用者修改除非他们创建一个子类。所有的method和property被认为是公有的，除非你显式标出他们是私有的或者被保护的。


require:
[Uncommon] 表明在模块声明中依赖的一个或者更多的其他模块的名字，多个名字可以是一个用逗号分开的列表。


default:
给property或attribute一个默认值，应该和"@type"成对来使用。


*uses
表示一个类中有其他的一些类的properties, methods, and other members组成自己的原型对象，可能是使用了"Y.mix()", "Y.Base.mix()", "Y.Base.create()"或其他相似的
方法。YUIDoc将会为这些properties, methods, and other members生成API文档，合在一起放在父类里，和链接到父类的文档。在YUIDoc的默认主题里，
用户可以决定混合在一起的成员是否被显示。
注意："@uses"不显示继承的东西。为了建立一个"is a“的关系，可以使用"@extends"。和"@extends"不同的是，你可以使用多个"@user"标签。


*example
表示例子代码将被自动解析并通过YUIDoc的MarkDown和代码高亮解析器来显示。你的代码样例必须放在"@example"标签的下放。
YUIDoc呈现所有样例通过高亮的<span>元素和其他标记。


chainable:
表明当前方法返回this指针(父对象)，这使的你能够通过同一个对象把其他的调用组成一个调用链。


deprecated
表明这个模块，类或成员不赞成您使用，将在以后的版本中移除。你能现在性地提供一个字符传信息来描述将用什么替代。




since：
表明这个模块，类或成员是在指定的版本里增加的。




async:
[Uncommon]：表明这个方式是异步的，需要传一个回调函数。


beta：
表明这个模块，类或成员正在测试使用，将来可能出现不向后兼容的改变


bubbles:
指定用户自定义事件的冒泡对象。如果你的API有一个管理类话，它将负责捕获相关自定义事件的集合，这是很有用的。


extension
extensionfor
extension_for


表示该class是一个扩展对象，用来选择性的混合到指定的类中。
@extensionfor几乎与@uses使用相反。关键不同点是 @uses 意思着 当前类总是将"used"的class 混合到自己的原型对象里。
而 @extensionfor 意思是 当前类被扩展到“extensionfor”的类里，但是它不受默认值影响。


带星号的的标签 表示你在同一注释块中多次使用。


能够被DocParser解析但是还不在主题中
author:关于这一项的作者信息
broadcast:向大范围用户发布的事件，而不是局部范围的。
*category：将这一项应该放进的目录


格式化扩展：
YUIDoc支持3种格式化文档的形式。即：HTML，Markdown,sellek.
html:生成的文档是标准的html标记语言
Markdown:全部Markdown语法也是被支持的。
Sellek:Sellek其他的语法也是被支持的。


标记语言和高亮代码
在注释块的内部，你可以使用基于标记语法的Markdown和Selleck，如果你在代码块中使用缩进，YUIDoc将会自动将他们包成一个代码块，并且把他们高亮显示。


穿插引用 模块和类：
YUIDoc 也包含一个 块帮助的把手，这可以使你能够很容易穿插引用类和模块，


使用自定义的块帮助把手：
你可以通过用-H 或--helpers 命令行参数（或 yuidoc.json文件里的helpers数组）让YUIDoc包含自定义的Y.handlebas帮助。