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
        */
  

And remember you just need to follow a pattern :)