Writing documentation

A typical ECMADoc documentation comments look similar like this:

/**
 * Gets a new array consisting of a combination of two or more arrays.
 * @syntax array1.concat([item1, [item2[, ...[, itemN]]]])
 * @arguments {Object} [0-n] Additional items to add to the end of this array. Optional.
 * @return {Array} The new combined array.
 */
Array.prototype.concat = function ()
{
}

What distinguishes an ECMADoc comment from regular comments is the second star (*) following the opening slash/star (/*) sequence:

/**
 * (the ECMADoc comment comes here) 
 */

The stars at the beginnings of the lines are optional, although it is common and seems to help visually distinguish the API documentation in code.

The first line in an ECMADoc comment is considered the summary for the block. Any subsequent lines until the first token or until the end of the comment are considered remarks. Tokens are keywords signified with an 'at' (@) symbol.

/**
 * This line is the summary for the code block I am documenting.
 * Starting here from the second line, is the remarks section for the
 * code block I am documenting. This section can be as long as required.
 * @author Igor Francé
 */
function MyFunction()
{
}

HTML Markup

The documentation text parsed by ECMADoc from comments is outputted to HTML without output escaping. For this reason, any HTML markup used in documentation will make it into the result documentation. This example shows free use of HTML list markup within an ECMADoc comment:

/**
 * An intrinsic global object that stores information about the results of regular expression pattern matches.
 * Available flags, which may be combined, are:
 * <ul>
 * <li><b>g</b> (global search for all occurrences of pattern)</li>
 * <li><b>i</b> (ignore case)</li>
 * <li><b>m</b> (multiline search)</li>
 * </ul>
 * @param {String} pattern The regular expression pattern to use.
 * @param {String} flags Combination of available flags.
 * @constructor
 */
function RegExp(pattern, flags)
{
}

Note that if there are mistakes such as unclosed tag left in the markup, the result when viewed in the browser can be unpredictable. Make sure that the hard-coded markup is well-formed and correct.

Linking to other types

To enable linking to other types in the project, ECMADoc provides several ways of specifying the item to link to. The three methods below are very similar in the way they work, choosing between them is a matter of style preference as functionally they are almost the same: