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.
Contents |
[edit] See Also
[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] 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.
[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) * @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); } });
[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. * * @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) { // ... }
[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() { }
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) { // ... });
