JSDoc Resources
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 *