API Docs Guidelines

Zeno Rocha edited this page Jan 15, 2014 · 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 :)