Firebug Source Code Comments

From FirebugWiki

(Difference between revisions)
Jump to: navigation, search
(Changed code blocks to use syntax highlighting)
(Added @lib tag + some other examples)
(One intermediate revision not shown)
Line 3: Line 3:
Also, an on-line [http://getfirebug.com/developer/api/firebug1.5 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 [http://code.google.com/p/jsdoc-toolkit/ jsdoc-toolkit].
Also, an on-line [http://getfirebug.com/developer/api/firebug1.5 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 [http://code.google.com/p/jsdoc-toolkit/ jsdoc-toolkit].
-
==Comment Tags==
+
== See Also ==
 +
* [http://getfirebug.com/wiki/index.php/Firebug_Coding_Style Firebug Coding Style]
 +
 
 +
== 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.
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.
Line 26: Line 29:
     * @domplate Represents a domplate template object (usually derived from Firebug.Rep)
     * @domplate Represents a domplate template object (usually derived from Firebug.Rep)
     * @service Represents a XPCOM Component (designed as a singleton)
     * @service Represents a XPCOM Component (designed as a singleton)
 +
    * @lib Represents an object part of the Firebug Library
See another example:
See another example:
Line 67: Line 71:
/**
/**
  * Converts provided text from Unicode to the specified charset.
  * Converts provided text from Unicode to the specified charset.
-
  * Throws an exception if the provided text uses encoding with
+
  *
 +
* @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.
  * embedded nulls.
  */
  */
Line 102: Line 112:
{
{
}
}
 +
</syntaxHighlight>
 +
This example renders [https://getfirebug.com/developer/api/firebug1.7/symbols/Firebug.Spy.html this description]:
 +
 +
<syntaxHighlight lang="javascript">
/**
/**
-
  * @module Represents a module in my Firebug extension.
+
  * @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.MyModule = extend(Firebug.Module,
+
Firebug.Spy = Obj.extend(Firebug.Module,
-
/** @lends Firebug.MyModule */
+
/** @lends Firebug.Spy */
{
{
-
    //...
+
  // ...
});
});
 +
</syntaxHighlight>
 +
 +
This one [http://fflorent.github.com/fbug-jsdoc/symbols/Obj.html this description]:
 +
<syntaxHighlight lang="javascript">
 +
/**
 +
* @name Obj
 +
* @lib Utility for objects
 +
*/
 +
var Obj = {};
 +
</syntaxHighlight>
 +
 +
This one [http://fflorent.github.com/fbug-jsdoc/symbols/Arr.html#.cloneArray this description]:
 +
<syntaxHighlight lang="javascript">
 +
 +
/**
 +
* 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)
 +
{
 +
    // ...
 +
});
 +
</syntaxHighlight>
</syntaxHighlight>

Revision as of 17:27, 13 January 2013

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