API Docs Guidelines

When you are writing source code documentation, make sure that...

• Methods are described using simple present tense;

  Wrong:

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

  Right:

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

• There's no <a> tag pointing to a broken url;

  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="Paginator.html#config_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
    * <code>total</code> attribute is specified.
    */
  

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