Documentation

EaselJS uses YUI Doc for documentation generation.

YUI Doc

• Official Yui Documentation
• Building Documentation with YUI Doc Slides
• Building Documentation Yui Doc Video and Transcript

Building Docs

In order to build the docs, you must first install and configure YUI Doc according to the instructions on the YUI Doc page.

Once YUI Doc is install and configured on your system, you can run the build_docs.bash bash script from the builds directory.

build_docs.bash path-to-yuidoc.py build_version

For example:

build_docs.bash ~/bin/yuidoc.py 0.3.0

This will generate the docs and place them in the build/output/docs directory.

Note, if the build script does not run, make sure it is set to be executable:

chmod 755 build_docs.bash

Documentation Conventions

In addition to support for built in types:

• Object
• Array
• String
• Boolean
• Number

You can also specify custom types, such as {Point}.

Multiple Types

You can specify that an argument takes multiple types like so:

 TYPE1 | TYPE2 | TYPE3 | ...

Array Types

You can specify that an Array expects a specific type like so:

 Array[TYPE]

NOTE : The Google Closure compiler gives a warning with the Array type syntax above. It expects Array types in the following format:

 Array.<TYPE>

However, in initial testing, the < > symbols broke the Yui Doc compiler. We will need to do some more testing once all of the docs are converted to Yui Doc.

Reserved Characters

The following charachters are not allowed in a param description:

“{” and “}”

In order to use these, you must use their HTML entity:

{ = &#123;
} = &#125;

Documentation Blocks

Modules

This block should be at the top (under the license) of every JavaScript file:

 /**
 * The Easel Javascript library provides a retained graphics mode for canvas 
 * including a full, hierarchical display list, a core interaction model, and 
 * helper classes to make working with Canvas much easier.
 * @module EaselJS
 **/

Class / Constructor

 /**
 * DESCRIPTION
 * @class CLASS_NAME
 * @extends SUBCLASS
 * @static REQUIRED IF CLASS SHOULD NOT BE INSTANTIATED
 * @constructor REQUIRED IF CLASS CAN BE INSTANTIATED
 * @param {TYPE} PARAM_NAME DESCRIPTION
 **/

Note, the description is required. If it is not included, Yui Doc will throw a stack trace and abort doc generation. There is a ticket logged for the issue here .

Methods

 /**
 * DESCRIPTION
 * @method METHOD_NAME
 * @static REQUIRED IF METHOD IS STATIC
 * @param {TYPE} PARAM_NAME DESCRIPTION
 * @return {TYPE} DESCRIPTION
 **/

Properties

 /**
 * DESCRIPTION
 * @property NAME
 * @static REQUIRED IF PROPERTY IS STATIC
 * @final REQUIRED IF PROPERTY IS READ-ONLY
 * @type TYPE
 **/

Events

Note, events must be declared after the class declaration for the class they are associated with.

 /**
 * DESCRIPTION
 * @event EVENT_NAME
 * @param {TYPE} NAME DESCRIPTION
 **/

Private / Protected Members

In general, all internal implimentation properties and methods should be marked as protected and not as private. Members should only be marked as private if they should not be accessed by subclasses.

It is not necessary to completely document protected APIs, although you should include the primary information:

 /** 
 * DESCRIPTION_OPTIONAL
 * @property NAME
 * @type TYPE
 * @protected 
 **/

or for a method:

 /** 
 * DESCRIPTION_OPTIONAL
 * @method NAME
 * @param {TYPE} NAME DESCRIPTION_OPTIONAL
 * @protected 
 **/