Writing Comments Overview

Documon reads JavaDoc style blocks, which take the form of:

/**
 * This is the traditional code-comment style
 * block, with stars along the left edge.
 * And this comment block is positioned
 * immeditely above the method or property.
 * 
 * @method myMethod
 * @param {type} arg description
 */
function myMethod(arg){
    var foo;
}

Where /** is used as a flag to designate the start of a documentation comment.

NOTE: You can designate a different "start" and "end" string if your language uses non-C-like commenting. See the "docBegin/End" options.

With Documon, you're not required to put stars down the left-hand side, you can do somehting like this:

/**

This is perfectly fine with Documon
For long, complicated comments with 
HTML and examples may be a liitle 
easier to write/read. Or if it's just 
your preference

@method myMethod
@param {type} arg description

*/
function myMethod(arg){
    var foo;
}

Blocks

A single comment block is defined for each:

• variable
• function
• event
• class

The block contains a general top area where the long description is written. THe long description is not required.

Tags appear after the long description. Tags are used to name, classify, categorize, link and generally describe the entity.

Tags can consume mulitple lines.

Be Robust

Documon doesn't read or interpret your source code, and relies soley on @tags within comments, hence, one of the following tags MUST exist within each code block:

• @package / @namespace
• @class / @module
• @method
• @property
• @event

The tags listed above are essential for Documon to construct the documentation website.

Example Property

/**
This is an example
@property foo
@type string
*/
var foo

or Documon's quick prop:

/**
@property {string} foo - description
*/
var foo

Example method

/**
This function does something
@method foo
@param {type} bar - description
@return {type} description
*/
function foo(bar){
    return bar + "hello";
}

Example class

/**
This class does something
@class foo
*/
function foo(bar){
    return bar + "hello";
}