Fork me on GitHub

YUIDoc Syntax Reference

Main Page > YUIDoc Syntax Reference
Jump to Table of Contents

YUIDoc's syntax should be familiar if you've used Javadoc, JSDoc, Doxygen, or other documentation generator tools. YUIDoc relies on tags such as @param or @return embedded in comment blocks that start with /** and end with */. See comment styles for more information. It includes a small number of tags for documenting specific YUI features, but most tags are generic enough to use with any object-oriented language.

IMPORTANT: YUIDoc only parses YUIDoc comment blocks, not source code. This keeps YUIDoc relatively simple and language agnostic. However, it also means you must declare everything to YUIDoc explicitly. A code snippet will not display as a "method" or "class" until you describe it as such. A corollary is that YUIDoc will never generate empty, "stub" doc entries for API members that lack comment blocks.

Basic Requirements

A given comment block must contain one (and only one) primary tag such as @class or @method, and zero or more secondary tags such as @param, @type, and @extends. Some secondary tags can be used in any comment block, while others only make sense alongside a particular primary tag.

A source tree must contain at least one comment block with a @module tag.

Each module must have at least one comment block with a @class tag.

Each class may then have zero or more comment blocks with an attribute, @class, @event, @method, or @property tag.

Primary Tags

Each comment block must have one (and only one) of the following tags:

Name Example Description
module
/**
 * Provides the base Widget class...
 *
 * @module widget
 */

Indicates that the block describes a group of related classes. For example, YUI's app module includes classes such as App.Base, Model, and Router. You can optionally break modules up into submodules.

YUIDoc requires you to provide at least one module per source tree. Since there isn't always an obvious place to insert module documentation in JavaScript source, the convention is to declare your module at the top of the file that contains your module's "primary" or "base" class.

See also: @class, @for, @main, @submodule.

main
/**
 * Provides more features for the widget module...
 *
 * @module widget
 * @submodule widget-foo
 * @main widget
 */

When YUIDoc parses a module's directory, there may be several files in this directory that provides documentation for that module and it's submodules. YUIDoc will attempt to determine which module contains the main description for this module. If it has trouble doing that, you can add a @main tag to your module/submodule description and YUIDoc will use this block as the main module description on the modules API landing page.

class
/**
 * A utility that brokers HTTP requests...
 *
 * @class IO
 * @constructor
 */
function IO (config) {

Indicates that the block describes a class. In JavaScript, this is generally an object with a constructor function. The value of @class should be the string that identifies the functional class on its parent object. For example, the @class for Y.DD.Drag would be Drag (and its @namespace would be DD).

YUIDoc expects methods, properties, attributes, and events to belong to a class, so in general you must provide at least one class for each module in your source tree. A @class block should reside just above the class's constructor function, and above all methods, events, properties, and attributes that belong to the class.

A @class tag should be paired with either a @constructor tag or a @static tag.

See also: @constructor, @extends, @extensionfor, @for, @module, @namespace, @static, @uses.

method
/**
 * Returns this model's attributes as...
 *
 * @method toJSON
 * @return {Object} Copy of ...
 */
toJSON: function () {

Indicates that the block describes a method for the current class. By default, the "current" class is the last class that YUIDoc parsed, but you can reset this with the @for tag.

A @method block should always reside directly above the method's definition. At a minimum, you should also document any parameters (@param) and return values (@return).

See also: @chainable, @class, @constructor, @for, @param, @return, @static.

event
/**
 * Fired when an error occurs...
 *
 * @event error
 * @param {String} msg A description of...
 */
var EVT_ERROR = 'error',

Indicates that the block describes a custom event that the class can fire at some interesting moment of code execution. An @event block is somewhat similar to a @method block, except that @return is irrelevant, and @param is used to describe properties hanging off the event object that callbacks listening for the event receive.

Ideally, an @event block should reside above the code that defines the event, even if that code is just a simple string declaration. If you find that your @event block is "floating in space," you should at least place it underneath the class that owns the event, grouped with any other events that the class can fire.

See also: @bubbles, @class, @for, @param.

property
/**
 * Template for this view's container...
 *
 * @property containerTemplate
 * @type String
 * @default "<div/>"
 */
containerTemplate: '<div/>',

Indicates that the block describes a property belonging to the current class.

As with methods, a @property block should always reside directly above the point where the property is defined. At a minimum, you should also provide the property's @type, even if the value is "any" or "mixed".

See also: @attribute, @default, @class, @for, @type.

attribute
/**
 * Indicates whether this Widget
 * has been rendered...
 *
 * @attribute rendered
 * @readOnly
 * @default false
 * @type boolean
 */
ATTRS[RENDERED] = {

[YUI-specific] Indicates that the block describes a managed configuration attribute. An attribute is an object created and managed by the YUI Attribute API. It is a kind of "super-property", with getters, setters, and other nifty features, including the ability to automatically fire change events.

An @attribute block should reside directly above the definition of the attribute, whether that is inside a Y.Base object's ATTRS property or elsewhere. Note that if your yuidoc.json file sets attributesEmit to true, YUI will automatically generate documentation for the attribute's change events throughout the source tree, with no extra YUIDoc comments needed from you.

See also: @property, @default, @class, @for, @type, @required, @optional.

Secondary tags

After choosing one of the five primary tags, you can further document a module, class, method, event or property with one or more of the following secondary tags.

Name Example Description
submodule
/**
 * @module app
 * @submodule view
 */

Specifies that the module is actually a submodule of some parent module. For example, the app-transitions module is a submodule of the larger app module.

In YUI, submodules enable you to make very fine-grained choices about loading code. For example, the foo module might have a minimal foo-core or foo-base submodule that supplies foo's basic functionality, plus additional foo-* modules that carry optional features. Using the YUI Loader, you can choose to load just foo-core, foo-core plus a couple of extra modules, or the entire foo "rollup".

See also: @module.

namespace
/**
 * @namespace Test.Mock
 */

Specifies a class's namespace. The @namespace should not include the "root" or "global" object that your entire library hangs off of. For example, Y.DD.Drag has a @class of Drag and a @namespace of DD, not Y.DD.

Supplying a @namespace enables you to refer to the class in YUIDoc using just the simple class name.

See also: @class.

extends
/**
 * @class View
 * @constructor
 * @extends Base
 */

Specifies that the class inherits members from a parent class, perhaps using Y.extend(), Y.Base.create(), or similar methods. YUIDoc will generate API documentation for methods, properties, events, and attributes inherited from the parent class, and link back to the parent class's documentation. In the default YUIDoc theme, users can toggle whether inherited members should display.

See also: @class, @extensionfor, @uses.

config
/**
 * @config docScrollX
 * @type Number
 */

[YUI-specific] Alias for @attribute. In older versions of YUI, @config was a slightly different take on attributes, but the two concepts have merged. Modern YUIDoc comments should use @attribute instead.

constructor
/**
 * @class IO
 * @constructor
 */

Indicates that the class is instantiable (created with the new keyword). A @class tag should be paired with either a @constructor tag or a @static tag.

See also: @class, @static.

static
/**
 * YUI user agent detection...
 *
 * @class UA
 * @static
 */

Indicates that the method or class is static:

  • For methods, indicates that the method is meant to be called without instantiating the class: var node = Y.Node.create('<div/>');
  • For classes, indicates that you should not instantiate the class with new. You can call all of the class's methods statically.

A @class tag should be paired with either a @constructor tag or a @static tag.

See also: @class, @constructor, @method.

final
/**
 * Identifies state changes
 * originating from...
 *
 * @property SRC_REPLACE
 * @type String
 * @static
 * @final
 */

Indicates that the property or attribute is a constant and should not be changed.

See also: @attribute, @property, @readOnly, @writeOnce.

readOnly
/**
 * The current default button
 * as configured through...
 *
 * @attribute defaultButton
 * @type Node
 * @default null
 * @readOnly
 */

[YUI-specific] Indicates that the attribute is configured with the readOnly property and cannot be changed by calling the set() method. Read-only attributes should always document their @default value.

Sometimes used with properties, as an alias for @final.

See also: @attribute, @default, @final, @property, @required, @optional, @writeOnce.

writeOnce
/**
 * Diameter of the circular
 * background object. Other
 * objects scale accordingly.
 * Set this only before
 * rendering.
 *
 * @attribute diameter
 * @type {Number} number of px
 * in diameter
 * @default 100
 * @writeOnce
 */

[YUI-specific] Indicates that the attribute is configured with the writeOnce property and can only be set once -- by applying a @default, by setting the value in the constructior, or by calling the set() method for the first time.

See also: @attribute, @default, @final, @required, @optional, @readOnly.

optional
/**
 * An optional attribute,
 * not required for proper
 * use.
 *
 * @attribute extras
 * @type {Object} extra data
 * @optional
 */

[YUI-specific] Indicates that the attribute is not required to be provided for proper use of this class.

See also: @attribute, @default, @final, @required, @readOnly.

required
/**
 * A required attribute
 * that is required for proper
 * use, module will likely fail
 * if this is not provided.
 *
 * @attribute url
 * @type {String} url to fetch remote data from
 * @required
 */

[YUI-specific] Indicates that the attribute is required to be provided for proper use of this class.

See also: @attribute, @default, @final, @optional, @readOnly.

*param
/**
 * @param {String} name An
 * Attribute name or
 * object property path.
 */
/**
 * @param {Object} [options] Data
 * to be mixed into the event
 * facade of the `change`
 * event(s) for these attributes.
 * @param {Boolean} [options.silent]
 * If `true`, no `change` event
 * will be fired.
 */

Defines a parameter for an ordinary @method, a parameter for a @constructor (generally defined inside a @class block), or a property that resides on an @event object. Can take either of the forms:

  • @param {type} name description
  • @param name {type} description

The {type} is optional, but if you include it, you must surround it in curly braces so that YUIDoc can distinguish it from the name. The name also has optional syntax:

  • [name] — optional parameter
  • [name=foo] — default value is foo
  • name* — placeholder for 1..n args
  • [name]* — placeholder for 0..n args

As shown in the example, you can also nest @param tags. This enables you to document object parameters that have their own particular nested structure.

See also: @class, @constructor, @event, @method, @return.

return
/**
 * @method generateClientId
 * @return {String} Unique clientId.
 */

Specifies a method's return value. A @return tag has the structure @return {type} description. The {type} is optional.

See also: @method, @param.

for
/**
 * Some inner class 'foo'...
 *
 * @class foo
 * @for OuterClass
 */
/**
 * Some method 'bar'
 * disconnected from
 * its class 'FarawayClass'...
 *
 * @method bar
 * @for FarawayClass
 */

Sets YUIDoc's class scope.

Using @for OuterClass in a @class block creates an inner class. YUIDoc will document methods and other items that follow that block as belonging to the inner class, but the inner class is correctly shown as belonging to its parent outer class.

To close an inner class, add @for OuterClass (again!) to the last @attribute, @event, @method, or @property block in the inner class. This resets the YUIDoc parser to use OuterClass as the owner of subsequent items.

If you are not inside an inner class, using @for FarawayClass in an @attribute, @event, @method, or @property block will attach all that item and subsequent items to the specified faraway class. This is useful when you have a module that attaches extra methods to a class's prototype, but the main class definition is in some entirely different file.

See also: @class, @method.

type
/**
 * @type String
 */
/**
 * @type HTMLElement|Node|String
 */

Specifies the type of a property or attribute. You can specify a single type, a list of legal types separated by vertical bars, or if you are lazy, "any" or "mixed".

See also: @attribute, @default, @property.

private
/**
 * Reference to the internal JSONP
 * instance used to make the queries.
 *
 * @private
 * @property _jsonp
 */

Indicates a member that should not be used externally. Although YUIDoc does not generate documentation for @private blocks, YUIDoc comments are still a nice, structured way to document internals in source code. All methods and properties are assumed to be public unless marked as private or protected.

See also: @protected.

protected
/**
 * Removes the `container` from
 * the DOM and ...
 *
 * @method _destroyContainer
 * @protected
 */

Indicates a member that should not be modified by implementers unless they are creating a subclass. All methods and properties are assumed to be public unless marked as private or protected.

See also: @private.

requires
/**
 * @module event-simulate
 * @requires event
 */

[Uncommon] Identifies one or more dependencies in the module declaration. Can be a single module name or a comma-separated list.

See also: @extends, @extensionfor, @module, @submodule.

default
/**
 * @default false
 */

Specifies the default value of a property or attribute. Should be paired with a @type tag.

See also: @attribute, @property, @type.

*uses
/**
 * @class Panel
 * @constructor
 * @extends Widget
 * @uses WidgetAutohide
 * @uses WidgetButtons
...
 */

Specifies that the class has some other class's properties, methods, and other members mixed into its prototype, perhaps using Y.mix(), Y.Base.mix(), Y.Base.create(), or similar methods. YUIDoc will generate API documentation for methods, properties, events, and attributes mixed into the parent class, and link back to the parent class's documentation. In the default YUIDoc theme, users can toggle whether mixed in members should display.

Note that @uses does not indicate inheritance. To establish an "is a" relationship, use @extends. Unlike @extends, you can provide multiple @uses tags.

See also: @class, @extends, @extensionfor.

*example
/**
 * @example
 *     model.set('foo', 'bar');
 */

Indicates a block of example code to be automatically parsed and displayed with YUIDoc's Markdown and code highlighting parser. Your code sample should be indented beneath the @example tag. YUIDoc displays all examples highlighted with <span> elements and other markup.

A block may include multiple @example tags.

chainable
/**
 * Renders this view ...
 *
 * @method render
 * @chainable
 */
render: function () {
    return this;
},

Indicates that a method returns this (the parent object), enabling you to chain it with other calls on the same object.

See also: @method.

deprecated
/**
 * @property locale
 * @type String
 * @deprecated Use `config.lang`
 * instead.
 */

Indicates that the module, class, or member is deprecated and will be removed in a future release. You can optionally supply a string message describing what to use instead.

See also: @beta, @since.

since
/**
 * @since 3.4.0
 */

Indicates that the module, class, or member was added to the source at the specified version.

See also: @beta, @deprecated.

async
/**
 * @async
 */

[Uncommon] Indicates that the method is asynchronous and requires a callback.

beta
/**
 * @beta
 */

Indicates that the method, class, or member is in beta and might undergo backwards-incompatible changes in the near future.

See also: @deprecated, @since.

bubbles
/**
 * Handles the mouseup DOM event...
 *
 * @event drag:mouseup
 * @bubbles DDM
 */

Specifies the default target that a custom event bubbles to. This is a useful tag if your API has a "manager" class that is responsible for capturing a set of related custom events.

See also: @event.

extension
extensionfor
extension_for
/**
 * @class PjaxBase
 * @extensionfor Router
 */

Indicates that the class is an extension object designed to be optionally mixed into the specified class.

@extensionfor is almost the inverse of @uses. The key difference is that @uses means, "this class always has the 'used' class mixed into its prototype," while @extensionfor means, "this class can be mixed into the 'extensionfor' class, but it isn't baked in by default."

See also: @class, @extends, @uses.

A * indicates that you can supply multiple tags of that type in the same block.

Parsed but not in the theme yet

The following tags are parsed by the DocParser but are not in the default theme yet.

author


    
Author information about this item
broadcast


    
Event broadcasts to a large audience than scoped
*category


    
Category to place this item into.

Comment Styles

The comment blocks can start with any amount of whitespace, and optionally one or more asterisks. Valid examples include:

/**
 * Description
 * @method description
 */

/**
 * Description
 * @method description
**/

/**
Description
@method description
*/

/**
Description
@method description
**/

Extra formatting

YUIDoc supports 3 main forms of formatting your documentation. HTML, Markdown & Selleck.

HTML Doc comments may contain standard HTML markup and YUIDoc will display it as is.
Markdown Full Markdown syntax is also supported.
Selleck Selleck's additional parsing is also supported.

Markdown and Code Highlighting

Inside any documentation block you may use Markdown or Selleck based markup. If you indent your code snippets, YUIDoc will automatically wrap them in a code block and syntax highlight them for you.

/**
 * This is the __module__ description for the `YUIDoc` module.
 *
 *     var options = {
 *         paths: [ './lib' ],
 *         outdir: './out'
 *     };
 *
 *     var Y = require('yuidoc');
 *     var json = (new Y.YUIDoc(options)).run();
 *
 * @class YUIDoc
 * @main yuidoc
 */

This would render as:

This is the module description for the YUIDoc module.

var options = {
    paths: [ './lib' ],
    outdir: './out'
};

var Y = require('yuidoc');
var json = (new Y.YUIDoc(options)).run();

Cross-referencing Modules and Classes

YUIDoc also includes a Handlebars blockHelper that enables you to easily cross-reference classes and modules. It uses this pattern:

#crossLink "Class/item:type"

#crossLink "Foo/bar:event"
#crossLink "Foo/bar:attribute"
#crossLink "Foo/bar:method" --default

So, for example, if you include:

/**
 *
 * This module also uses {{#crossLink "Foo"}}{{/crossLink}}, where Foo is a class name.
 * Also see {{#crossLink "myClass/Foo:method"}}{{/crossLink}}, where myClass is a class name and Foo is a method on that class.
 *
 * This module uses {{#crossLinkModule "widget"}}{{/crossLinkModule}}, where widget is a module name
 *
 * This module also uses {{#crossLink "Bar"}} an awesome class {{/crossLink}} named Bar.
 */

This automatically generates an internal link to Foo's API reference page:

<p>
This module also uses <a href="../classes/Foo.html" class="crosslink">Foo</a>, 
where Foo is a class or module name.
</p>
<p>
Also see <a href="../classes/myClass.html#method_Foo">Foo</a>, where myClass 
is a class name and Foo is a method on that class.
</p>
<p>
This module uses <a href="../modules/widget.html">widget</a>, where widget is a module name
</p>
<p>
This module also uses <a href="../classes/Bar.html" class="crosslink">an awesome class</a>
named Bar.
</p>

You can also call crossLinkRaw to retun only the HREF portion of the link, so you can link it yourself.

Using custom Handlebars block helpers

You can tell YUIDoc to include custom Y.Handlebars helpers with the -H or --helpers command line arguments (or helpers Array in the yuidoc.json file). Here is an example helper.js file:

module.exports = {
    davglass: function(item) {
        return "Dav Glass says: " + item
    }
};

Now you can use the davglass helper inside your own docs like this:

/**
 * This is also a test {{#davglass "Foo"}}{{/davglass}}
 */
This will output this in your documentation:
<p>
 This is also a test Dav Glass says: Foo
</p>