Welcome GuestLogin

Writing documentation

RSS
Modified on Monday, 28 December 2009 03:48 by Administrator Categorized as Uncategorized
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:

  • <c>...</c>
    This tag has a twofold purpose. On one hand, it can be used to specify a member. On the other, it serves as a shorthand for <code>...</code>. Therefore, ECMADoc will first attempt to resolve the value as a member, and if successful it will replace it with an HTML link to that member. If resolving was unsuccessful, it will simply substitute the <c>...</c> with <code>...</code> thereby wrapping the contents with <code>...</code>.

  • <see type="MyClass.method1"/>
    This tag will insert a link to the member specified with the type attribute, if the member can be resolved. If the specified member cannot be resolved, the specified name without the link will appear in the HTML, wrapped in <code>...</code> tags.

  • {@see MyClass.method1}
    This inline token behaves identically to the <see type="...."/> tag described above. It's simply an alternative way of specifying the same information.

ScrewTurn Wiki version 3.0.4.560. Some of the icons created by FamFamFam.