YUIDoc Syntax

Main Page > YUIDoc Syntax

Jump to Table of Contents

YUIDoc parses a modified form of JSDoc tags, here we will list the most common tags used and how they are parsed.

/**
* This is the description for my class
* @class MyClass
* @constructor
*/

/**
* My method description.  Like other pieces of your comment blocks, 
* this can span multiple lines.
* @method methodName
* @param {String} foo Argument 1
* @param {Object} config A config object
* @param {String} config.name The name on the config object
* @param {Function} config.callback A callback function on the config object
* @param {Boolean} [extra=false] Do extra, optional work
* @return {Boolean} Returns true on success
*/

/**
* My property description.  Like other pieces of your comment blocks, 
* this can span multiple lines.
* @property propertyName
* @type {Object}
*/

Primary Tags

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

module There must be one module per source tree. By convention, put your module declaration at the top of the file that contains the main class for your module.
class The string identifying the functional class on its parent object; for example, the class for Y.DD.Drag would be Drag (and its @namespace would be DD).
method The name of a method on the current class.
event In YUI, events are Custom Events fired off programmatically at interesting moments in a component's execution. The event tag is similar to method, but there is no return tag and i ts params are arguments passed to the event listener.
property The name of a property on the current class.

Secondary tags

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

submodule YUIDoc supports the notion that a module is a submodule of a parent module. For example, in YUI 3 anim-scroll is a submodule of anim. A submodule encompasses a subset of the parent module's functionality. To use submodule designation, provide the parent module's name as the module property and the submodule's name in the submodule property.
namespace While it is optional to provide a namespace, it is recommended. This lets you describe your class just with the name: For example, Y.DD.Drag has a namespace of Y.DD and a class of Drag.
extends Sets up an inheritance relationship between the current class and a parent class; API docs will show and link to items inherited from the parent class.
config A config is a managed configuration attribute. In YUI parlance, this is typically an attribute created and managed with the Config class (part of the Container Family).
attribute An attribute is a managed configuration attribute. In YUI parlance, this is typically an attribute created and managed with AttributeProvider (part of the [YUI Element Utility][[yui-element]]). An attribute is similar to a config, but YUIDoc will autogenerate documentation for the change events associated with the attribute as provided by Element. (Note: Unless you're using YUI and referring to an attribute managed by AttributeProvider, you should avoid using this tag.)
constructor The presence of this tag (which requires no description) indicates that this class is instantiable.
static If a class does not have a constructor, then the static tag should be present to signal that it is a static class.
final For constants and for read-only configs and attributes.
param Defined as @param {type} name description or @param name {type} description, params can be used with classes, methods and events. Use [name] to indicate the param is optional, name* to indicate it is a place holder for 1..n arguments, and [name*] for 0..n arguments.
return Defined as @return {type} description.
for Used to define an inner class:
/**  
* An inner class  
* @class foo  
* @for OuterClass  
*/
After the class is done, you need to inform the parser to start working on the outer class again:
/**  
* Another method for the outer class  
* @method bar  
* @for OuterClass  
*/
type For properties, configs and attributes.
private Privates by default are suppressed from the API docs. All methods and properties are assumed to be public unless marked as private.
protected Used to designate members that should not be modified by implementers unless they are creating a subclass.
requires Used to identify dependencies in the module declaration.
default The default value of a property, config or attribute.
uses For classes that use some kind of Object augmentation. If this object is defined and YUIDoc parses it, the properties from the "used" object will be deisplayed in the output.

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.

Examples

/**
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 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();

Crosslinking

We have also added a blockHelper in Handlebars that will allow you to "cross-link" your documentation together.

/**

This module also uses {{#crossLink Foo}}, where Foo is a class or module name.

*/

This will generate an internal link to the other's API document.

This module also uses <a href="../classes/Foo.html" class="crosslink">Foo</a>, where Foo is a class or module name.