Introduction |
|
JSDoc is a tool that parses inline documentation in JavaScript source files, and produces an documentation of the JavaScript code. This is typically in the form of HTML (example), but XML and XMI (UML) export are also supported. JSDoc is based on the (very successful) JSDoc is primarily intended for libraries of object-oriented JavaScript files, although it also works with procedural code. There is a basic ability to determine inheritance built into the parser, although some more obscure dynamic constructs will not be understood (for example, defining a method to set one class as the superclass of another).
Anyone familiar with the |
Installation |
|
JSDoc is implemented in Perl, as as such, requires the perl executable. This shouldn't be a problem for Linux/Unix users, but Windows users will probably have to install a perl runtime; ActivePerl is recommended.
JSDoc is distributed as a gzipped tarball, and can be downloaded from the JSDoc project page. Once you have downloaded JSDoc-x-x.tgz, just unpack it (tar zxf JSDoc-x-x.tgz on Linux/Unix, use WinZip on Windows), and you're ready to go. You can immediately try out JSDoc on the included test.js JavaScript file by going into the JSDoc directory and entering the command
perl jsdoc.pl test.js
This should output a set of HTML files in a directory called js_docs_out.
If you get an error message right away that looks something like
Can't locate HTML/Template.pm in @INC ......
then you will need to install the HTML::Template Perl module. Luckily, this is a very trivial operation thanks to the CPAN. In a Linux/Unix/POSIX-style operating system, open a terminal and run the following command as root:
# perl -MCPAN -e 'install HTML::Template'
If you're running Windows and ActivePerl, open a command prompt window and enter the following command:
C:\> ppm
This will start the Perl Package Manager; at the PPM prompt, enter the following two commands (PPM> is the PPM prompt):
PPM> install HTML-Template
PPM> quit
JSDoc should run without problems now. |
Usage |
|
The general idea of JSDoc is to pick up the form and documentation of code. A major part of JSDoc's functionality is based around documentation strings embedded in JavaScript code. The definitive reference to writing documentation strings for Java (with a large amount of carry-over to JSDoc) can be found at the javadoc reference page. JSDoc currently supports a subset of javadoc's '@'-prefixed attributes, but the parser is customizable (as explained later). An example JavaScript file (test.js) is included with the JSDoc distribution. Most functionality of JSDoc can be seen within this script file, however for the impatient a small (and incomplete) example of a common usage of JSDoc is shown below
/**
* Shape is an abstract base class. It is defined simply
* to have something to inherit from for geometric
* subclasses
* @constructor
*/
function Shape(color){
this.color = color;
}
// Bind the Shape_getColor method to the Shape class
Shape.prototype.getColor = Shape_getColor;
/**
* Get the name of the color for this shape
* @returns A color string for this shape
*/
function Shape_getColor(){
return this.color;
}
/**
* Circle is a subclass of Shape
*/
function Circle(radius){
this.radius = radius;
}
/**
* A very rough value for pi
*/
Circle.PI = 3.14;
/**
* Get the radius of this circle
* @returns The radius of this circle
*/
function Circle_getRadius(){
return this.radius;
}
// Circle is a subclass of Shape
Circle.prototype = new Shape(null);
One important difference between javadoc and JSDoc is that JSDoc deals with a much more dynamic language that javadoc. For example, in JavaScript there are many different ways to make one class a subclass of another. The JSDoc parser is able to catch some of these methods, but for particularly dynamic scripts the parser will not be able to do it all on its own. For that reason, JSDoc is customizable with a file called .jsdoc_config that resides in the JSDoc install directory. In this configuration file, JSDoc's behaviour can be customized for any kind of '@'-prefixed attribute. Although this configuration file actually contains Perl code, simple customizations can be done by someone with minimal experience with Perl. JSDoc also uses a several non-javadoc '@'-attributes:@constructor and @private are two of the most important ones. As noted above, JavaScript has the capability to be a much more dynamic language than Java. The JSDoc parser can usually find class constructors on it's own, but there are some situations when it needs some additional assistance. For this reason, it is a good practice to always include the @constructor tag in the documentation for a class constructor, as shown below:
/**
* Nothing is a class that represents nothing
* @constructor
*/
function Nothing(){
// ... initialization ...
}
The @private attribute simply displays the marked method as being private.
To get more information on the use of the jsdoc.pl executable itself, run it with the |
Tag Reference |
||||||||||||||||||||||||||||||||||||||||||||||||
The following is a summary of the supported tags ('@'-attributes) that are supported by JSDoc. For actual examples of the usage of these tags, please see the test.js JavaScript file that is included in the JSDoc distribution.
|
Frequently Asked Questions |
|
More Information |
|
A very complete and informative article (written by Rainer Eschen) on the use of JSDoc can be found at Webetiser. The article is based on JSDoc 1.5, but is still very relevant. I've been told that the article will be updated in the near future. As noted above, the definitive reference for writing Java docstrings can be found at the javadoc reference page. Please send comments, bugs, complaints, requests for additional information, and whatever else to the JSDoc mailing list. |