JSDoc

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.

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.{{cite web |url=https://github.com/mozilla/rhino/tree/master/examples/jsdoc.js |title=Rhino example: jsdoc.js |publisher=Mozilla project |date=May 6, 1999 |website=GitHub}}

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.{{cite web |title=JSDoc |url=https://sourceforge.net/projects/jsdoc/ |website=SourceForge |date=15 April 2013 |language=en}} [https://github.com/gabrielreid/JSDoc Git conversion] 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.{{cite web |title=jsdoc-toolkit |url=https://code.google.com/archive/p/jsdoc-toolkit/ |website=Google Code}} [https://github.com/h13i32maru/jsdoc-toolkit Git conversion] By 2011 he has refactored the system into JSDoc 3.0 and hosted the result on GitHub. It now runs on Node.js.{{cite web |title=JSDoc |url=https://github.com/jsdoc/jsdoc |website=GitHub |publisher=jsdoc |access-date=4 September 2019 |date=4 September 2019}}

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

:

/** @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 {{code|@class}} and {{code|@constructor}} tags can in fact be omitted: the ECMASyntax is sufficient to make their identities clear, and JSDoc makes use of that.{{cite web |title=ES 2015 Classes |url=https://jsdoc.app/howto-es2015-classes.html |website=Use JSDoc}} {{code|@override}} can be automatically deduced as well.{{cite web |title=@override |url=https://jsdoc.app/tags-override.html |website=Use JSDoc}}

• 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.{{Cite web| url=https://www.typescriptlang.org/docs/handbook/type-checking-javascript-files.html| title=Type Checking JavaScript Files| website=TypeScript Documentation}} 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 {{ISBN|1-59059-582-3}}.
• Various products of JetBrains, like IntelliJ IDEA and WebStorm, NetBeans, Visual Studio Code and RubyMine understand JSDoc syntax.
• Eclipse-based Aptana Studio supports ScriptDoc.
• Mozile, the Mozilla Inline Editor uses JSDoc.pm.
• The Helma application framework uses JSDoc.
• SproutCore documentation was generated using JSDoc.
• Visual Studio, WebStorm and many other Integrated development environments or Text Editors offer Code Completion and other assistance based on JSDoc comments.
• Open source Atom editor supports JSDoc via the atom-easy-jsdoc plugin.

• Comparison of documentation generators
• Google Closure Tools

{{reflist}}

• {{Official website|https://jsdoc.app}}
• {{github|jsdoc3/jsdoc}}
• {{cite web |url= http://code.google.com/closure/compiler/docs/js-for-compiler.html |title= Annotating JavaScript for the Closure Compiler |series= Closure Tools documentation |website= Google Developer }}

{{JavaScript}}

{{ECMAScript}}

Category:Free documentation generators

Category:Source code documentation formats

Category:JavaScript programming tools