JSDoc

JSDoc is a syntax for adding inline API documentation to JavaScript source code. This is distinct from the various tools that parse and manipulate code that follows the JSDoc syntax.

The JSDoc syntax is similar to the Javadoc syntax, used for documenting Java code, but is specialized to work with JavaScript's more dynamic syntax and therefore unique, as it is not completely compatible with Javadoc. However, like Javadoc, JSDoc allows the programmer to create doclets and tags which can then be translated into published output, like HTML or RTF.

JSDoc tags

Although this list is incomplete, the following annotations are commonly used in modern JSDoc.

Tag	Description
@author	Developer's name
@constructor	Marks a function as a constructor
@deprecated	Marks a method as deprecated
@exception	Synonym for @throws
@param	Documents a method parameter; a datatype indicator can be added between curly braces
@private	Signifies that a method is private
@return	Documents a return value
@see	Documents an association to another object
@this	Specifies the type of the object to which the keyword "this" refers within a function.
@throws	Documents an exception thrown by a method
@version	Provides the version number of a library

Example

An example of JSDoc usage.

/**
 * Creates an instance of Circle.
 *
 * @constructor
 * @this {Circle}
 * @param {number} r The desired radius of the circle.
 */
function Circle(r) {
    /** @private */ this.radius = r;
    /** @private */ this.circumference = 2 * Math.PI * r;
}
 
/**
 * Creates a new Circle from a diameter.
 *
 * @param {number} d The desired diameter of the circle.
 * @return {Circle} The new Circle object.
 */
Circle.fromDiameter = function (d) {
    return new Circle(d / 2);
};
 
/**
 * Calculates the circumference of the Circle.
 *
 * @deprecated
 * @this {Circle}
 * @return {number} The circumference of the circle.
 */
Circle.prototype.calculateCircumference = function () {
    return 2 * Math.PI * this.radius;
};
 
/**
 * Returns the pre-computed circumference of the Circle.
 *
 * @this {Circle}
 * @return {number} The circumference of the circle.
 */
Circle.prototype.getCircumference = function () {
    return this.circumference;
};
 
/**
 * Find a String representation of the Circle.
 *
 * @override
 * @this {Circle}
 * @return {string} Human-readable representation of this Circle.
 */
Circle.prototype.toString = function () {
    return "A Circle object with radius of " + this.radius + ".";
};

History

The earliest example of using a Javadoc-like syntax to document JavaScript was released in 1999 with the Netscape/Mozilla project named Rhino.

JSDoc In Use

• Google's Closure Linter and Closure Compiler [1]. The latter extracts the type information to optimize its output JavaScript.
• The JSDoc syntax has been described at length in the Apress book Foundations of Ajax ISBN 1-59059-582-3.
• IntelliJ IDEA, NetBeans and RubyMine understand JSDoc syntax.
• The Eclipse IDE has extensions that understand the JSDoc syntax. Eclipse-based Aptana Studio supports ScriptDoc, and the included JavaScript files are commented in ScriptDoc.
• Mozile, the Mozilla Inline Editor uses JSDoc.
• The Helma application framework uses JSDoc.
• SproutCore documentation was generated using JSDoc. [2]

See also

• Comparison of documentation generators

External links

• Annotating JavaScript for the Closure Compiler
• Create useful relevant JavaScript documentation with JSDoc
• Javadoc Tool: How to Write Doc Comments for the Javadoc Tool