Developer Network Home - Help

Yahoo! UI Library: YUI Doc

Yahoo! UI Library: YUI Doc

YUI Doc is a Python application used at build time to generate API documentation for JavaScript code. YUI Doc is comment-driven and supports a wide range of JavaScript coding styles. The output of YUI Doc is API documentation formatted as a set of HTML pages including information about methods, properties, custom events and inheritance for JavaScript objects. YUI Doc was written for the YUI Project by Adam Moore; it uses YUI JavaScript and CSS in the generated files (primarily for AutoComplete-driven API instant search); and it supports common YUI conventions like Custom Events. That said, it can be used easily and productively on non-YUI code.

Sample API documentation output from the YUI Doc tool.

YUI Doc is most helpful to developers who are building an API for external consumption or for developers who are building library code that will be shared by others on their team.

YUI Doc is stable and has been used since 2005 as part of the YUI Project. Its public release is currently designated as a beta, which means that the API is expect to evolve further based on response from users.

For discussion about and support of YUI Doc usage and development, check out the YUI Doc Community Forum on Yahoo! Groups.

Getting Started

Note: The use of YUI Doc requires some ability to drive a computer from the command line and is most useful as part of an automated build process. The instructions here are high-level and assume some familiarity with CLIs and with the installation of command-line tools and libraries.

  1. Download YUI Doc from YUILibrary.com: YUI Doc is available from the YUI project website, but it is a separate download from the YUI JavaScript/CSS library and the YUI Compressor.
  2. Install the required external libraries: YUI Doc relies on Python and four external libraries. If you have Python and setuptools installed, you can use easy_install to install the latest versions of these libraries. More info on the install process is included in the INSTALL file inside the source distribution. For more information on these tools, please visit their respective project pages:
  3. Review the documentation format: The included TAGS document is your best resource for learning about how to format your code comments for YUI Doc. The Tags section below provides a summary of the key primary and secondary tags.
  4. Configure and run YUI Doc: The included example.sh file is a template for executing YUI Doc against your JavaScript code; copy this file and configure it with the correct directory paths for your own environment.

Overview of YUI Doc Concepts

YUI Doc is Comment-Driven

YUI Doc is a comment-parsing engine. It looks at comment-blocks in source files to find specific tags; when it finds a comment with a supported tag, it attempts to parse the comment and aggregate its information into the metadata it builds about your JavaScript application. Comment blocks should take the form of:

Every comment block that you want YUI Doc to process should contain one (and only one) of the following tags: module, class, property, method, or event.

The Relationship Between Source Trees, Modules and Classes

YUI Doc processes files in each source tree specified in your configuration file. For example, in example.sh there is one source tree defined:

Each source tree specified in the parser_in variable should contain a directory/subdirectory structure containing the source file(s) for a single "module". A module, in the YUI Doc idiom, is a group of JavaScript objects that, taken together, represent a coherent unit of functionality. In the YUI Library's usage, modules represent components — the event module contains all of the classes comprising the YUI Event Utility. You can see the YUI Doc API output for the Event Utility here; the event module contains four physical files and five classes.

One and only one module should be defined for each source tree.

A common module definition might look like this:

A module may be spread across any number of files, but each file in a module's source tree (including those in subdirectories) should have a unique name. Each file can contain one or more classes. Classes can be instantiable (in which case the @constructor tag should be used in defining the class) or static (@static).

Primary and Secondary Tags

YUI Doc supports a discrete set of tags. For the current, comphrehensive list of tags, refer to the TAGS file accompanying the distribution.

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

Tag Name Notes
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 YAHOO.util.Event would be Event (and its @namespace would be "YAHOO.util").
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 its params are arguments passed to the event listener.
property The name of a property on the current class.

Each of these primary tags requires a description at the head of the tag:

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.

Tag Name Notes
submodule YUI Doc supports the notion that a module is a submodule of a parent module. For example, in YUI 3.x 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, YAHOO.util.Event has a namespace of YAHOO.util and a class of Event.
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). An attribute is similar to a config, but YUI Doc 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.
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.
required Used to identify dependencies in the module declaration.
default The default value of a property, config or attribute.
uses For classes that use YAHOO.lang.augmentProto or YAHOO.lang.augmentObject. Optional method/properties (supplied to augmentProto or augmentObject) are not parsed by YUI Doc.

Customizing the YUI Doc Templates

The template directory within the distribution contains the templating files used to structure YUI Doc's output. The most important files here are these:

  1. main.tmpl: This file provides the HTML structure for all meaningful output pages.
  2. assets/api.css: This is the core CSS file for the output documents.

YUI Doc's output relies on the YUI CSS foundation: Reset CSS, Fonts CSS, and Grids CSS, all of which accompany the distribution in template/assets/reset-fonts-grids-min.css.

Support & Community

The YUI Library and related topics are discussed on the on the ydn-javascript mailing list.

In addition, please visit the YUIBlog for updates and articles about the YUI Library written by the library's developers.

Filing Bugs & Feature Requests

The YUI Library's public bug tracking and feature request repositories are located on the YUILibrary.com site. Before filing new feature requests or bug reports, please review our reporting guidelines.

Examples:

YUI Doc on del.icio.us:

Copyright © 2009 Yahoo! Inc. All rights reserved.

Privacy Policy - Terms of Service - Copyright Policy - Job Openings