Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

API Docs Guidelines

Zeno Rocha edited this page · 12 revisions

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 :)

Something went wrong with that request. Please try again.