An application programming interface is a source code based specification intended to be used as an interface by software components to communicate with each other...
JavaScript is a prototype-based scripting language that is dynamic, weakly typed and has first-class functions. It is a multi-paradigm language, supporting object-oriented, imperative, and functional programming styles....
source code. This is distinct from the various tools that parse and manipulate code that follows the JSDoc syntax.
Javadoc is a documentation generator from Sun Microsystems for generating API documentation in HTML format from Java source code.The "doc comments" format used by Javadoc is the de facto industry standard for documenting Java classes. Some IDEs, such as Netbeans and Eclipse automatically generate...
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
HTML
HyperText Markup Language is the predominant markup language for web pages. HTML elements are the basic building-blocks of webpages....
RTF may stand for:* Radiodiffusion-Télévision Française, France's national public broadcasting organization between 1949 and 1964* Reader talks first, in RFID, the situation where the interrogator or reader initiates the session with the RFID tag...
.
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.prototype.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.
The JSDoc syntax has been described at length in the Apress book Foundations of Ajax ISBN 1-59059-582-3.
IntelliJ 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.
