JSDoc

Source: Wikipedia, the free encyclopedia.
Initial release1999; 25 years ago (1999)
JavaDoc
Open format?Yes
Websitejsdoc.app

JSDoc is a

Apache License 2.0
.

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

An early example using a Javadoc-like syntax to document JavaScript was released in 1999 with the

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

All main generations of "JSDoc" were headed by micmaths (Michael Mathews). He started with JSDoc.pm in 2001, a simple system written in

Google Code.[4] By 2011 he has refactored the system into JSDoc 3.0 and hosted the result on GitHub. It now runs on Node.js.[1]

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
@returns Documents a return value
@return Synonym for @returns
@see Documents an association to another object
@todo Documents something that is missing/open
@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

/** @class Circle representing a circle. */
class Circle {
  /**
   * 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.
   */
  static fromDiameter(d) {
    return new Circle(d / 2)
  }

  /**
   * Calculates the circumference of the Circle.
   *
   * @deprecated since 1.1.0; use getCircumference instead
   * @return {number} The circumference of the circle.
   */
  calculateCircumference() {
    return 2 * Math.PI * this.radius
  }

  /**
   * Returns the pre-computed circumference of the Circle.
   *
   * @return {number} The circumference of the circle.
   * @since 1.1.0
   */
  getCircumference() {
    return this.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
 */
function printCircle(circle) {
    /** @this {Circle} */
    function bound() { 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.[5] @override can be automatically deduced as well.[6]

JSDoc in use

  • Google's Closure Linter and
    Closure Compiler
    . The latter extracts the type information to optimize its output JavaScript.
  • TypeScript can perform type checking for JavaScript files with JSDoc type annotations.[7] Microsoft has specified a new TSDoc language with extensible tags.
  • 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 .
  • Various products of JetBrains, like
    RubyMine
    understand JSDoc syntax.
  • Eclipse-based
    Aptana Studio
    supports ScriptDoc.
  • Mozile Archived 2018-10-06 at the Wayback Machine, the Mozilla Inline Editor uses JSDoc.pm.
  • The Helma application framework uses JSDoc.
  • SproutCore documentation was generated using JSDoc. [1]
  • 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

References

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

External links

This page is based on the copyrighted Wikipedia article: JSDoc. Articles is available under the CC BY-SA 3.0 license; additional terms may apply.Privacy Policy