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.
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.
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`. |
| `element` | ``` /** * This is the foo element description... * * @element x-foo */ ``` |
Indicates that the block describes a Custom Element. The `@attribute` tag works as a attribute of the element when you specify a `@element` tag. You can also specify the `@parents`, `@contents`, and `@interface` tag for the element. See also: `@attribute`, `@parents`, `@contents`, `@interface`. |
| `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`, `@throws`, `@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 "" */ containerTemplate: '', ``` |
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. If you specify a `@element` tag, the `@attribute` tag works as a attribute of the element. See also: `@element`, `@property`, `@default`, `@class`, `@for`, `@type`, `@required`, `@optional`. |
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. |
| `static` | ``` /** * YUI user agent detection... * * @class UA * @static */ ``` |
Indicates that the method or class is static:
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:
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:
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. |
| `throws` | ``` /** * @method generateClientId * @throws {Error} An error. */ ``` |
Specifies an error which method throws. A `@throws` tag has the structure `@throws {type} description`. The `{type}` is optional. |
| `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. |
| `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 `` 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. |
| `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`. |
| `parents` | ``` /** * @element x-foo * @parents */ ``` |
It's a secondary tag for the `@element` tag. Indicates that the parent element of the element you specified. See also: `@element`, `@attribute`, `@contents`, `@interface`. |
| `contents` |
```
/**
* @element x-foo
* @contents |
It's a secondary tag for the `@element` tag. Indicates that the element contains in the element you specified. See also: `@element`, `@attribute`, `@parents`, `@interface`. |
| `interface` | ``` /** * @element x-foo * @interface XFooElement */ ``` |
It's a secondary tag for the `@element` tag. Indicates that the interface for the element you specified. See also: `@element`, `@attribute`, `@parents`, `@contents`. |
A * indicates that you can supply multiple tags of that type in the same block.
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. |
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 **/ ```
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. |
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.
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:
```This module also uses Foo, where Foo is a class or module name.
Also see Foo, where myClass is a class name and Foo is a method on that class.
This module uses widget, where widget is a module name
This module also uses an awesome class named Bar.
```You can also call `crossLinkRaw` to return only the HREF portion of the link, so you can link it yourself.
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: ```This is also a test Dav Glass says: Foo
```