Firebug Source Code Comments

From FirebugWiki

Revision as of 17:27, 13 January 2013 by Florent (Talk | contribs)
Jump to: navigation, search

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.

Contents

See Also

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.


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)
   * @lib Represents an object part of the Firebug Library

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);
    }
});

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.
 *
 * @param {string} text The text to convert
 * @param {string} charset
 *
 * @return {string} the converted text
 *
 * @throws {Error} an exception if the provided text uses encoding with
 * embedded nulls.
 */
function convertFromUnicode(text, charset)
{
    // ...
}

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()
{
}

This example renders this description:

/**
 * @module Represents a XHR Spy module. The main purpose of the XHR Spy feature is to monitor
 * XHR activity of the current page and create appropriate log into the Console panel.
 * This feature can be controlled by an option <i>Show XMLHttpRequests</i> (from within the
 * console panel).
 *
 * The module is responsible for attaching/detaching a HTTP Observers when Firebug is
 * activated/deactivated for a site.
 */
Firebug.Spy = Obj.extend(Firebug.Module,
/** @lends Firebug.Spy */
{
   // ...
});

This one this description:

/**
 * @name Obj
 * @lib Utility for objects
 */
var Obj = {};

This one this description:

/**
 * Clone an array. If a function is given as second parameter, the function is called for each
 * elements of the passed array and the results are put in the new one.
 *
 * @param {Array or Array-Like object} [array] The array
 * @param {function} [fn] The function
 *
 * @deprecated Use either Array.slice(array) or Array.map(array, fn) instead. 
 * see https://developer.mozilla.org/en-US/docs/JavaScript/Reference/Global_Objects/Array
 *
 */
Arr.cloneArray = Deprecated.deprecated("use either Array.slice or Array.map instead",
function(array, fn)
{
    // ...
});
Personal tools