Firebug Source Code Comments

From FirebugWiki

(Difference between revisions)
Jump to: navigation, search
(JSHint)
(One intermediate revision not shown)
Line 21: Line 21:
See the list of all supported tags [http://code.google.com/p/jsdoc-toolkit/w/list here].
See the list of all supported tags [http://code.google.com/p/jsdoc-toolkit/w/list here].
 +
== JSHint Comments ==
 +
 +
In order for [http://www.jshint.com/ JSHint] to validate code according to local coding style, comments with options to it may exist at the top of some files. Example:
 +
 +
<syntaxHighlight lang="javascript">
 +
/*jshint forin:false, noempty:false, esnext:true, es5:true, curly:false */
 +
/*global FBTrace:true, Components:true, define:true, KeyEvent:true */
 +
</syntaxHighlight>
 +
 +
The "jshint" line contains options to JSHint; "esnext:true", "es5:true" and "curly:false" are particularly recommended, but this can vary on a file-by-file basis.
 +
 +
The "global" line contains the global names that JSHint may assume to exist (aside from standardized ones available in every web browser); at least "FBTrace" and "require" should be there.
 +
 +
Read more in the [http://www.jshint.com/docs/ JSHint documentation].
==Firebug Specific Tags==
==Firebug Specific Tags==
Line 29: Line 43:
     * @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 70: Line 85:
/**
/**
  * 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 105: Line 126:
{
{
}
}
 +
</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 22:36, 1 February 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.

JSHint Comments

In order for JSHint to validate code according to local coding style, comments with options to it may exist at the top of some files. Example:

/*jshint forin:false, noempty:false, esnext:true, es5:true, curly:false */
/*global FBTrace:true, Components:true, define:true, KeyEvent:true */

The "jshint" line contains options to JSHint; "esnext:true", "es5:true" and "curly:false" are particularly recommended, but this can vary on a file-by-file basis.

The "global" line contains the global names that JSHint may assume to exist (aside from standardized ones available in every web browser); at least "FBTrace" and "require" should be there.

Read more in the JSHint documentation.

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