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 Small OL

The output can be seen in the  NaturalDocs sandbox.

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.

/**
 * Start of comment block
 *
 * End of comment block
 */

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.

var object = {
    /**
     * Property: name
     * {type} Describe the property here
     */
    name: value
}

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.

var object = {
    /**
     * Function: functionName
     * Describe the function here
     *
     * Parameters:
     * param1 - {String} Describe param1 here
     * param2 - {<OpenLayers.Map>} Describe param2 here
     */
    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.

var object = {
    /**
     * Function: functionName
     * Describe the function here
     *
     * Parameters:
     * param1 - {String} Describe param1 here
     * param2 - {<OpenLayers.Map>} Describe param2 here
     * 
     * Return:
     * {Number} Describe the return here
     */
    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.

/**
 * 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.create();
OpenLayers.Layer.WMS.prototype = 
  OpenLayers.Class.inherit( 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.

/**
 * 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.create();
OpenLayers.Layer.WMS.prototype = 
  OpenLayers.Class.inherit( OpenLayers.Layer.Grid, {
    /**
     * Constructor: OpenLayers.Layer.WMS
     * Create a new WMS layer object
     *
     * 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
     *
     * Return:
     * A new OpenLayers.Layer.WMS instance
     */
    initialize: function(name, url, params, options) {
        // some code here
    }
    
});

Private Methods and Properties

Make the first word of the description "*Private*."

var object = {
    /**
     * Method: myPrivateMethod
     * *Private*. This is some text about a private method.
     */
    myPrivateMethod: function() {},

    /**
     * Property: myPrivateProperty
     * *Private*. This is some text about a private property.
     */
    myPrivateProperty: "some private value"
}