JSDoc
JSDoc, along with other documentation tools such as CppDoc, PHPDoc, and JavaDoc, are used to provide an easier way to document code. JSDoc, along with the other tools saves a lot of time by keeping the comments both reliable and up to date. All a developer needs to do is update his/her comments, run the tool and the documentation is available to anyone who needs to use it via the web.
One of the nicer features of JSDoc is that the parser is customizable via the tag options. It is able to distinguish similarly written methods, along with catching the classes and subclasses. The parser can also find class constructors on its own, but sometimes misses them.
Installing JSDoc
There are two different ways to install JSDoc- If you are installing it on a Windows Environment, go here. If you are installing it on a Linux Enviroment, go here.
Using JSDoc
Once JSDoc is installed, you must comment your javascript code to generate the documentation. The comment blocks are similar to those of phpdoc and cppdoc. Start off the comment with /** and add * to each subsequent line. Finish the block with */. JSDoc also has an extensive list of tags for parameters, return values, author information, class information and much more. A full list of tags can be found at http://jsdoc.sourceforge.net/#usage. Here is a sample block of jsdoc documentation:
/** * getXMLHTTPRequest creates an object that sends HTTP Requests to the server *@constructor *@returns an HTTP Request Object */
The first line starts the block off. Next is a description of the function, followed by @constructor. This is to denote that the function is a constructor. The final line before the ending */ states the function returns something, where that something is an HTTP Request Object.