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

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

@module widget
**/
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
/**
A utility that brokers HTTP requests...

@class IO 
@constructor
**/
function IO (config) {
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
/**
Returns this model's attributes as...

@method toJSON
@return {Object} Copy of ...
**/
toJSON: function () {
The name of a method on the current class.
event
/**
Fired when an error occurs...

@method error 
@param {String} msg A description of...
**/
var EVT_ERROR = 'error',
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
/**
Template for this view's container...

@property containerTemplate 
@type String
@default "<div/>"
**/
containerTemplate: '<div/>',
The name of a property on the current class.

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
**/
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
/**
@namespace Test.Mock
**/
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
/**
@class View
@constructor
@extends Base
**/
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
/**
@config docScrollX 
@type Number 
**/
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
/**
* Indicates whether this Widget
* has been rendered...
*
* @attribute rendered
* @readOnly
* @default false
* @type boolean
*/
ATTRS[RENDERED] = {
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
/**
@class IO 
@constructor
**/
The presence of this tag (which requires no description) indicates that this class is instantiable.
static
/**
YUI user agent detection...

@class UA
@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
/**
Identifies state changes originating...

@property SRC_REPLACE
@type String
@static
@final
**/
For constants and for read-only configs and attributes.
*param
/**
@param {String} name 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=false] 
      If `true`, no `change` event will 
      be fired.
**/
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
/**
@method generateClientId
@return {String} Unique clientId.
**/
Defined as @return {type} description.
for
/**  
An inner class  
@class foo  
@for OuterClass  
**/
Used to define an inner class: 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
/**
@type String
**/
/**
@type HTMLElement|Node|String 
**/
For properties, configs and attributes. You can specify a single type, a list of legal types separated by vertical bars, or if you are lazy, "mixed".
private
/**
Reference to the internal JSONP 
instance used to make the queries.

@private
@property _jsonp
**/
Privates by default are suppressed from the API docs. All methods and properties are assumed to be public unless marked as private or protected.
protected
/**
Removes the `container` from 
the DOM and ...
 
@method _destroyContainer
@protected
**/
Used to designate members that should not be modified by implementers unless they are creating a subclass.
requires
/**
@module event-simulate
@requires event
**/
Used to identify dependencies in the module declaration.
default
/**
@default false
**/
The default value of a property, config or attribute.
*uses
/**
@class Panel
@constructor
@extends Widget
@uses WidgetAutohide
@uses WidgetButtons
...
**/
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 displayed in the output.
*example
/**
@example
    model.set('foo', 'bar');
**/
Items with this tag are automatically parsed with the Markdown and Code parser and displayed below the item. The code is not included raw, only in highlight form
chainable
/**
Renders this view ...

@method render
@chainable
**/
render: function () {
    return this;
},
**/
Method returns itself so you can chain it with other calls on this object.
deprecated
/**
@property locale
@type String
@deprecated Use `config.lang` instead.
**/
Item is deprecated and will be removed in a future release.
since
/**
@since 3.4.0
**/
Item was added to the source in this version.
async
/**
@async
**/
Method is async and requires a callback. Uncommon.
beta
/**
@beta
**/
Item should be marked as in beta. Uncommon.
bubbles
/**
Handles the mouseup DOM event...

@event drag:mouseup
@bubbles DDM
**/
Event bubbles to another target
extension
extensionfor
extension_for
/**
@class PjaxBase
@extensionfor Router
**/
Item is an extension of passed Item.
* Denotes that it supports multiple tags in the same doc 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.

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 is what the above would render to:

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.

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