TAGS

General Notes:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

--General Notes:

* All comment blocks should have one, and only one, of the following tags: 
  module, class, property, method.  If one is not supplied, the parser will
  complain and the block will likely be skipped.

* The four block types require a description.  This description should appear
  as the first thing in your comment block.

  /**
   * My method description.  Like other pieces of your comment blocks, 
   * this can span multiple lines.
   * @method methodName
   */

  This might work too, but I have not tried it.. I like the other convention:

  /**
   * @method       methodName
   * @description  My method description.  Like other pieces of your 
   * comment blocks, this can span multiple lines.
   */

* It will warn about any tag that does not contain a description, with the
  exception of the following: constructor, public, private, static


Supported Tags:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

@module modulename
    Include one these blocks in one of your files for your util/widget. The
    description will appear on the splash page.

    NOTE: At least one @module is required.  Put one of these near the top
    of your source and use it to describe your component.  Do not combine
    @module with @class.

@namespace YAHOO.namespace
    While it is optional to provide a namespace, it is recommended. This lets you
    describe your class just with the name: YAHOO.util.Event -> Event.  It only
    needs to be included one time as long as this is the first file that is parsed.
    Probably safer to put it in each file.

@class ClassName

@extends YAHOO.namespace.ClassName

@property propertyName

@config configName
    similar to @property, but separates config items from normal properties

@attribute configName
    similar to @config, but also auto-generates the [event]Change and 
    the before[Event]Change events

@method methodName

@event
    similar to @method, but no @return, and the @params define the signature
    the listeners are executed with.

@constructor
    Only put this if the class can be instantiated

@static
    For classes, methods, properties, etc ...
    Probably should have either @constructor or @static in the @class block

@final
    for constants (properties and read-only configs)

@param {type} name description    -or-
@param name {type} description
    Supported in method blocks or class/constructor blocks.

@for ClassName
    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
         */

@return {type} description
    for methods

@type type
    for properties and configs

@see
    This is barely supported at this point

@deprecated explaination
    The explaination does not need to be provided, but the parser will warn if 
    you don't.  Usually you'll want to say what to use instead

@public
    Allowed to exist as a singular tag, but does nothing.  Everthing is assumed 
    public unless marked private

@private
    Use to mark that the method/property should not be accessed by implementers
    (even if it is accessible to them).  By default, privates are not present
    in the api docs.

@protected
    Use to indicate the method/property should not be accessed by implementers
    unless they are subclassing.

@requires module1, module2
    Supported in the @module declaration.  The comma separated list of module
    short names will eventually be matched against a lookup table when
    cross-linking is supported

@default
    The default value of a property or config

@uses YAHOO.namespace.ClassName [method1, method2]
    For classes that use YAHOO.augment
    The optional method/properties are not supported yet