JSDoc

JSDoc is a markup language used to annotate JavaScript source code files. Using comments containing JSDoc, programmers can add documentation describing the application programming interface of the code they're creating. This is then processed, by various tools, to produce documentation in accessible formats like HTML and Rich Text Format.

History

The earliest example of using a Javadoc-like syntax to document JavaScript was released in 1999 with the Netscape/Mozilla project Rhino, a JavaScript run-time system written in Java.^[1]

JSDoc's syntax and semantics are similar to those of the Javadoc scheme, which is used for documenting code written in Java. JSDoc differs from Javadoc, in that it is specialized to handle JavaScript's dynamic behaviour.

JSDoc tags

Some of the more popular annotation tags used in modern JSDoc are:

Tag	Description
@author	Developer's name
@constructor	Marks a function as a constructor
@deprecated	Marks a method as deprecated
@exception	Synonym for @throws
@exports	Identifies a member that is exported by the module
@param	Documents a method parameter; a datatype indicator can be added between curly braces
@private	Signifies that a member is private
@return	Documents a return value
@returns	Synonym for @return
@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

/**
 * 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 + ".";
};

JSDoc in use

• Google's Closure Linter and Closure Compiler. The latter extracts the type information to optimize its output JavaScript.
• Popular editor Sublime Text supports JSDoc through the DocBlockr or DoxyDoxygen plugin
• 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.
• Visual Studio, WebStorm and many other Integrated development environments or Text Editors offer Code Completion and other assistance based on JSDoc comments.
• Open source Atom editor supports JSDoc via the atom-easy-jsdoc plugin.

See also

• Comparison of documentation generators
• Google Closure Tools

References

External links

• Official JSDoc Website, for tutorials and docs on usage
• Official JSDoc Github, for up-to-date code
• "Annotating JavaScript for the Closure Compiler", Closure Tools documentation, Google Developer website