API Docs Guidelines

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

• 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) Every piece of code is wrapped into a <code> tag;

  Wrong:

   /**
    * Sets the activeIndex attribute to the previous index.
    *
    * @method _updateIndexPrev
    * @param options
    * @protected
    */
  

  Right:

   /**
    * Sets the <code>activeIndex</code> attribute to the previous index.
    *
    * @method _updateIndexPrev
    * @param options
    * @protected
    */
  

And remember you just need to follow a pattern :)