JSDoc

Last updated
Initial release1999;26 years ago (1999)
Latest release
4.0.4 [1]
19 October 2024;3 months ago (2024-10-19)
Type of format Programming documentation Format
Contained by JavaScript source files
Extended from JavaDoc
Open format?Yes
Website jsdoc.app

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. The JSDoc specification is released under CC BY-SA 3.0, while its companion documentation generator and parser library is free software under the Apache License 2.0.

Contents

History

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. [2]

An early example 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. It included a toy "JSDoc" HTML generator, versioned up to 1.3, as an example of its JavaScript capabilities. [3]

All main generations of "JSDoc" were headed by micmath (Michael Mathews). He started with JSDoc.pm in 2001, a simple system written in Perl. Later, with contributions by Canadian programmer Gabriel Reid. It was hosted on SourceForge in a CVS repository. [4] By JSDoc 1.0 (2007) he rewrote the system in JavaScript (again for Rhino), and after a set of expansions JSDoc 2.0 (2008) gained the name "jsdoc-toolkit". Released under the MIT License, it was hosted in a Subversion repository on Google Code. [5] By 2011 he has refactored the system into JSDoc 3.0 and hosted the result on GitHub. It now runs on Node.js. [2]

JSDoc tags

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

TagDescription
@authorDeveloper's name
@constructorMarks a function as a constructor
@deprecatedMarks a method as deprecated
@exceptionSynonym for @throws
@exportsIdentifies a member that is exported by the module
@paramDocuments a method parameter; a datatype indicator can be added between curly braces
@privateSignifies that a member is private
@returnsDocuments a return value
@returnSynonym for @returns
@seeDocuments an association to another object
@todoDocuments something that is missing/open
@thisSpecifies the type of the object to which the keyword this refers within a function.
@throwsDocuments an exception thrown by a method
@versionProvides the version number of a library

Example

/** @class Circle representing a circle. */classCircle{/**   * Creates an instance of Circle.   *   * @author: moi   * @param {number} r The desired radius of the circle.   */constructor(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.   */staticfromDiameter(d){returnnewCircle(d/2)}/**   * Calculates the circumference of the Circle.   *   * @deprecated since 1.1.0; use getCircumference instead   * @return {number} The circumference of the circle.   */calculateCircumference(){return2*Math.PI*this.radius}/**   * Returns the pre-computed circumference of the Circle.   *   * @return {number} The circumference of the circle.   * @since 1.1.0   */getCircumference(){returnthis.circumference}/**   * Find a String representation of the Circle.   *   * @override   * @return {string} Human-readable representation of this Circle.   */toString(){return`[A Circle object with radius of ${this.radius}.]`}}/** * Prints a circle. * * @param {Circle} circle */functionprintCircle(circle){    /** @this {Circle} */    functionbound(){console.log(this)}bound.apply(circle)}

Note that the @class and @constructor tags can in fact be omitted: the ECMASyntax is sufficient to make their identities clear, and JSDoc makes use of that. [6] @override can be automatically deduced as well. [7]

JSDoc in use

See also

References

  1. "Releases · jsdoc/jsdoc". GitHub.
  2. 1 2 "JSDoc". GitHub. jsdoc. 4 September 2019. Retrieved 4 September 2019.
  3. "Rhino example: jsdoc.js". GitHub. Mozilla project. May 6, 1999.
  4. "JSDoc". SourceForge. 15 April 2013. Git conversion
  5. "jsdoc-toolkit". Google Code. Git conversion
  6. "ES 2015 Classes". Use JSDoc.
  7. "@override". Use JSDoc.
  8. "Type Checking JavaScript Files". TypeScript Documentation.