Firebug Source Code Comments

From FirebugWiki

Since source code documentation is a fundamental engineering practice critical to efficient development process, here are some recommendations how to properly create comments in Firebug's source code.

Also, an on-line API Reference documentation is generated from the source code and this process utilizes some comment-tags to provide organized and browsable overview of the code. Just to note that the documentation is generated using jsdoc-toolkit.

[edit] Comment Tags

Comments processed by jsdoc-toolkit are based on JavaDoc like syntax, where various tags instructs the processor that generates the resulting documentation. Here is a simple example.

/**
 * @param userName The name of the user.
 */
function getAge(userName)
{
    // ...
}

See the list of all supported tags here.

[edit] Firebug Specific Tags

In order to generate a documentation that closely reflects Firebug architecture, there are also some Firebug's specific tags.

   * @module Represents a Firebug Module object (derived from Firebug.Module)
   * @panel Represents a Firebug Panel object (derived from Firebug.Panel)
   * @domplate Represents a domplate template object (usually derived from Firebug.Rep)
   * @service Represents a XPCOM Component (designed as a singleton)

See another example:

/**
 * @module This object represents a module
 * that is responsible for...
 */
Firebug.MyModule = extend(Firebug.Module,
/** @lends Firebug.MyModule */
{
    /**
     * Called by Firebug when Firefox is closed.
     */
    shutdown: function()
    {
        Firebug.Module.initialize.apply(this, arguments);
    }
});

[edit] Valuable Comments

The information content of a comment should be valuable. It should provide an information that is not directly obvious from the source code.

See an example of a comment with LOW informative value.

/**
 * Converts the text from Unicode to a charset.
 */
function convertFromUnicode(text, charset)
{
    // ...
}

Here is another example that shows MORE useful comment.

/**
 * Converts provided text from Unicode to the specified charset.
 * Throws an exception if the provided text uses encoding with
 * embedded nulls.
 */
function convertFromUnicode(text, charset)
{
    // ...
}

[edit] Further Examples

Take a look at a few extra examples using various tags (see also jsdoc-toolkit's cookbook).

/**
 * Comments can use HTML markup to <b>highlight</b> important facts.
 */
function getData()
{
}
 
/**
 * A comment can link to an existing object (that is also commented).
 * For example, this method opens {@link Firebug.Dialog1} if the
 * provided user is a man and {@link Firebug.Dialog2} if the user
 * is a woman.
 */
function showDialog(user)
{
}
 
// Still valid but, no documentation is generated
// from this comment.
function theMostImportantFunction()
{
}
 
/**
 * @module Represents a module in my Firebug extension.
 */
Firebug.MyModule = extend(Firebug.Module,
/** @lends Firebug.MyModule */
{
    //...
});