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. |
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>