Documentation with JSDoc

JSDoc Resources

Note

JSDoc is written in Perl, so you'll need to have Perl installed to run it.

JSDoc documents JavScript files like JavaDoc documents Java files. It takes specially formatted comments from the code file and generates HTML documentation files. Here's an example from Mozile:

Example 3.6. JSDoc example

/**
 * Inserts the newNode after the refNode in the refNode's parent node.
 * @param {Node} newNode The node to insert.
 * @param {Node} refNode Insert the new node after this node.
 * @type Node
 */
mozile.dom.insertAfter = function(newNode, refNode) {

The opening /** indicates to JSDoc that it should pay attention to this comment. The first sentence describes the function. The @param statements indicate parameters for the function. The {Node} entry tells JSDoc that the parameter's type is Node. The parameter also includes a name and description. Finally @type provides the return type of the function. The JSDoc homepage provides a full list of tags and their usage.

We use JSDoc in all of the files in the code directory, as well as in all JavaScript files and most CSS and XML files throughout Mozile. New JSDoc HTML files are generated before every Mozile release, and periodically between releases. You don't need to update the HTML files yourself when you make a change to Mozile, but please keep the JSDoc comments in the source files up to date.

To generate the JSDoc HTML files, we first remove all the *.html files in doc/jsdoc. Then we run the JSDoc script over all the files in src, using the -d option to set the destination directory:

cd ~/working_copy/mozilewww/0.8/src/
/path/to/jsdoc.pl -d ../doc/jsdoc *

Important

Please write and revise JSDoc comments for the code you're working on, so that the API documentation is always up-to-date.