Firebug Source Code Comments

From FirebugWiki

(Difference between revisions)
Jump to: navigation, search
(Firebug is using an extra line for '{' so, follow the rule even in examples.)
(Changed code blocks to use syntax highlighting)
Line 6: Line 6:
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.
-
<pre class="code">
+
<syntaxHighlight lang="javascript">
/**
/**
  * @param userName The name of the user.
  * @param userName The name of the user.
Line 14: Line 14:
     // ...
     // ...
}
}
-
</pre>
+
</syntaxHighlight>
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].
Line 29: Line 29:
See another example:
See another example:
-
<pre class="code">
+
<syntaxHighlight lang="javascript">
/**
/**
  * @module This object represents a module
  * @module This object represents a module
Line 45: Line 45:
     }
     }
});
});
-
</pre>
+
</syntaxHighlight>
==Valuable Comments==
==Valuable Comments==
Line 52: Line 52:
See an example of a comment with LOW informative value.
See an example of a comment with LOW informative value.
-
<pre class="code">
+
<syntaxHighlight lang="javascript">
/**
/**
  * Converts the text from Unicode to a charset.
  * Converts the text from Unicode to a charset.
Line 60: Line 60:
     // ...
     // ...
}
}
-
</pre>
+
</syntaxHighlight>
Here is another example that shows MORE useful comment.
Here is another example that shows MORE useful comment.
-
<pre class="code">
+
<syntaxHighlight lang="javascript">
/**
/**
  * Converts provided text from Unicode to the specified charset.
  * Converts provided text from Unicode to the specified charset.
Line 74: Line 74:
     // ...
     // ...
}
}
-
</pre>
+
</syntaxHighlight>
==Further Examples==
==Further Examples==
Take a look at a few extra examples using various tags (see also jsdoc-toolkit's [http://code.google.com/p/jsdoc-toolkit/wiki/CookBook cookbook]).
Take a look at a few extra examples using various tags (see also jsdoc-toolkit's [http://code.google.com/p/jsdoc-toolkit/wiki/CookBook cookbook]).
-
<pre class="code">
+
<syntaxHighlight lang="javascript">
/**
/**
  * Comments can use HTML markup to <b>highlight</b> important facts.
  * Comments can use HTML markup to <b>highlight</b> important facts.
Line 111: Line 111:
     //...
     //...
});
});
-
</pre>
+
</syntaxHighlight>

Revision as of 07:20, 18 May 2011

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

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)

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.
 * Throws 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()
{
}
 
/**
 * @module Represents a module in my Firebug extension.
 */
Firebug.MyModule = extend(Firebug.Module,
/** @lends Firebug.MyModule */
{
    //...
});
Personal tools