JSDoc

From Wikipedia, the free encyclopedia
Jump to: navigation, search

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[edit]

The earliest example[citation needed] 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[edit]

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[edit]

/**
 * 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[edit]

See also[edit]

References[edit]

  1. ^ "jsdoc.js". Mozilla project. May 6, 1999. 

External links[edit]