API Docs Guidelines

All code should be properly documented using YUIDoc syntax, so when you are writing source code documentation, make sure that...

• 1) Methods are described using simple present tense;

  Wrong:

   /**
    * Go to the next index.
    *
    * @method next
    */
  

  Right:

   /**
    * Goes to the next index.
    *
    * @method next
    */
  

• 2) There's no HTML tag, only Markdown will be accepted;

  Wrong:

   /**
    * Holds the page items as a NodeList. The list could be queried
    * from the DOM trough Widget HTML_PARSER or generated if
    * <a href="Pagination.html#attr_total">total</a> attribute is specified.
    */
  

  Right:

   /**
    * Holds the page items as a NodeList. The list could be queried
    * from the DOM trough Widget HTML_PARSER or generated if
    * [total](Pagination.html#attr_total) attribute is specified.
    */
  

• 3) Every description ends with a dot;

  Wrong:

   /**
    * A formatter function to format each pagination item
    *
    * @attribute formatter
    * @type Function
    */
  

  Right:

   /**
    * A formatter function to format each pagination item.
    *
    * @attribute formatter
    * @type Function
    */
  

• 4) Line break should use 80 columns for comments;

  Wrong:

/**

• If true the render phase will be automatically invoked preventing the .render() manual call.
• @attribute render
• @type Boolean */

  
  *Right:*
  
  

/**

• If true the render phase will be automatically invoked

• preventing the .render() manual call.

• @attribute render

• @type Boolean */

• 5) Always wrap @param with {Type} for consistency;

  Wrong:

/**

• A base class for Audio.
• @param config {Object} Object literal specifying widget configuration properties. */

  
  *Right:*
  
  

/**

• A base class for Audio.
• @param {Object} config Object literal specifying widget configuration properties. */

And remember you just need to follow a pattern :)