Essentials of Javascript - Cultural View

JSDoc 88
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.
Example
An example of JSDoc usage.
/**
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
* 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.