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.
Yahoo! frontend engineer Stephen Woods provides a guided tour to YUI's documentation engine, YUI Doc. YUI Doc is language-agnostic and can be used to document a variety of project styles.
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.
easy_installto install the latest versions of these libraries. More info on the install process is included in the
INSTALLfile inside the source distribution. For more information on these tools, please visit their respective project pages:
TAGSdocument 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.
- * @tagname tagcontent
/** * * @tagname tagcontent * */
Every comment block that you want YUI Doc to process should contain one (and only one) of the following tags:
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
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:
- * The ProfilerViewer module provides a graphical display for viewing
- * the output of the YUI Profiler <https://developer.yahoo.com/yui/profiler>.
- * @module profilerviewer
- * @requires yahoo, dom, event, element, profiler, yuiloader
/** * The ProfilerViewer module provides a graphical display for viewing * the output of the YUI Profiler <https://developer.yahoo.com/yui/profiler>. * @module profilerviewer * @requires yahoo, dom, event, element, profiler, yuiloader */
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 (
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:
|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
|method||The name of a method on the current class.|
|property||The name of a property on the current class.|
Each of these primary tags requires a description at the head of the tag:
- * My method description. Like other pieces of your comment blocks,
- * this can span multiple lines.
- * @method methodName
/** * My method description. Like other pieces of your comment blocks, * this can span multiple lines. * @method methodName */
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||YUI Doc supports the notion that a module is a submodule of a parent module. For example, in YUI 3.x
|namespace||While it is optional to provide a namespace, it is recommended. This lets you describe your class just with the name: For example,
|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.|
|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
|final||For constants and for read-only
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
|default||The default value of a property, config or attribute.|
|uses||For classes that use
template directory within the distribution contains the templating files used to structure YUI Doc's output. The most important files here are these:
main.tmpl: This file provides the HTML structure for all meaningful output pages.
assets/api.css: This is the core CSS file for the output documents.
The YUI Library and related topics are discussed on the on the YUILibrary.com forums.
Also be sure to check out YUIBlog for updates and articles about the YUI Library written by the library's developers.
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.
be the first to bookmark this page!
All YUI 2.x users should review the YUI 2.8.2 security bulletin, which discusses a vulnerability present in YUI 2.4.0-2.8.1.