API Documentation with Natural Docs

OpenLayers API documentation is build with Natural Docs. This documentation is built with the following

NaturalDocs -i lib -o HTML doc -p doc_config -s Default OL

There are a number of conventions we need to adopt in our coding in order to make the output documentation more useful. The following is a rough list, meant to be refined as we go.

Comment Style

OpenLayers comment blocks follow this convention. This is not required, but should be adhered to.

/**
 * Paragraphs start here.
 *
 * Space between paragraphs.  Lines wrap at 80 characters.  Long paragraphs are
 *     indented with four extra spaces.  Lorem ipsum dolor sit amet,
 *     consectetuer adipiscing elit. Phasellus ornare.  Integer luctus lectus
 *     sed est.  Suspendisse potenti.  Aliquam nec mi. Sed nec sapien.
 */

Property Types

Natural Docs doesn't have a keyword for specifying property types. OpenLayers code documentation uses {braces} around types, and {<angle brackets>} around types (classes) that exist in the library.
Note that all text up until the first "." will be displayed at the top of the doc as the short description. At the bottom, the short and long descriptions will both be listed.
Also note the indentation style. Remember that lines should be 79 characters or less!

var object = {
    /**
     * Property: name
     * {type} Short Description. And the rest of the Full Description
     *     is here for your reading convenience.
     */
    name: value
}

Methods and Parameter Types

As with property types, there is no keyword to specify parameter types. OpenLayers code documentation uses {braces} around types, and {<angle brackets>} around types (classes) that exist in the library. Also as with properties, the "." marks the division between the short and long descriptions of the method.
Also note the indentation style. Remember that lines should be 79 characters or less!

var object = {
    /**
     * Function: functionName
     * Short Description about our method. And the Full Description would 
     *     be here, in all its great glory. A full description is a beautiful
     *     thing and hopefully we can have lots of them.
     *
     * Parameters:
     * param1 - {String} Describe param1 here so that everyone will know
     *     just exactly what to pass. 
     * param2 - {<OpenLayers.Map>} Describe param2 here so that those same
     *     folks from above won't get confused.
     */
    functionName: function(param1, param2) {
        // do something
    }
}

Return Types

As above, there is no keyword to specify a function return type. Again, OpenLayers code documentation uses {braces} around types, and {<angle brackets>} around types (classes) that exist in the library.
Also note the indentation style. Remember that lines should be 79 characters or less!

var object = {
    /**
     * Function: functionName
     * Describe the function here.
     *
     * Parameters:
     * param1 - {String} Describe param1 here
     * param2 - {<OpenLayers.Map>} Describe param2 here
     * 
     * Returns:
     * {Number} Describe the return here because how is anyone 
     *     supposed to know what a function does if it does not
     *     have a clearly documented return function?
     */
    functionName: function(param1, param2) {
        // do something
    }
}

Class Definitions and Inheritance

In addition to using the Class keyword, a link should be placed to the constructor. Any classes that this one inherits from should be listed as shown below.
Also note the indentation style. Remember that lines should be 79 characters or less!

/**
 * Class: OpenLayers.Layer.WMS
 * Description of the wms layer class.  Instances of this class 
 *     are created with the <OpenLayers.Layer.WMS> consructor,
 *     just as you would have imagined.
 *
 * Inherits from:
 *  - <OpenLayers.Layer.Grid>
 */
OpenLayers.Layer.WMS = OpenLayers.Class(OpenLayers.Layer.Grid, {
    // class definition here
});

Constructor Methods

When documenting a class, use the Constructor keyword, and name the constructor as you would call it when instantiating an object.
Also note the indentation style. Remember that lines should be.... 79 characters or less!

/**
 * Class: OpenLayers.Layer.WMS
 * Description of the wms layer class.  Instances of this class 
 *     are created with the <OpenLayers.Layer.WMS> consructor.  
 *
 * Inherits from:
 *  - <OpenLayers.Layer.Grid>
 */
OpenLayers.Layer.WMS = OpenLayers.Class(OpenLayers.Layer.Grid, {
    /**
     * Constructor: OpenLayers.Layer.WMS
     * Create a new WMS layer object. This class should be used 
     *     responsibly by adults of the specified  age. If you are unsure
     *     of how to operate the WMS layer, you better ask somebody.
     *
     * Parameters:
     * name - {String} A name for the layer
     * url - {String} Base url for the WMS
     *     (e.g. http://wms.jpl.nasa.gov/wms.cgi)
     * params - {Object} An object with key/value pairs representing the
     *     GetMap query string parameters and parameter values.
     * options - {Ojbect} Hashtable of extra options to tag onto the layer
     */
    initialize: function(name, url, params, options) {
        // some code here
    }
    
});

Private Methods and Properties

Everything is assumed to be private (not part of the API that people should rely on) unless it is prefixed with API. There will be two separate documentation directories, one for the development docs and one for the API docs. To make a property, method, or function show up in the API docs, use the keywords APIProperty, APIMethod, and APIFunction. The development doc building process recognizes these keywords in addition to all the normal aliases. The API doc building process ignores keywords like Property, Method, and Function and only recognizes their counterparts with the API prefix.

var object = {
    /**
     * Method: myPrivateMethod
     * Short Description about a private method. And the Full Description.
     */
    myPrivateMethod: function() {},

    /**
     * Property: myPrivateProperty
     * {String} Short Description about a private property. And the 
     *     Full Description afterwards. Para variar.
     */
    myPrivateProperty: "some private value"

    /**
     * APIMethod: myPublicMethod
     * Short Description about a public method. And the Full Description.
     */
    myPublicMethod: function() {},

    /**
     * APIProperty: myPublicProperty
     * {String} Short Description about a public property. And the 
     *     Full Description. Musico en vivo cada noche.
     */
    myPublicProperty: "some public value"
}

Note that keywords like Constructor, and Class always go in the API docs (they don't need the API prefix). This is the same for Topic, File, and anything else that is not a keyword for the Function and Property topics (see the Natural Docs keyword documentation for a full list).