JSDoc is a

markup language Markup language refers to a text-encoding system consisting of a set of symbols inserted in a text document to control its structure, formatting, or the relationship between its parts. Markup is often used to control the display of the document ...

used to annotate

JavaScript JavaScript (), often abbreviated as JS, is a programming language that is one of the core technologies of the World Wide Web, alongside HTML and CSS. As of 2022, 98% of Website, websites use JavaScript on the Client (computing), client side ...

source code In computing, source code, or simply code, is any collection of code, with or without comments, written using a human-readable programming language, usually as plain text. The source code of a program is specially designed to facilitate the wo ...

files. Using comments containing JSDoc, programmers can add documentation describing the

application programming interface An application programming interface (API) is a way for two or more computer programs to communicate with each other. It is a type of software interface, offering a service to other pieces of software. A document or standard that describes how t ...

of the code they're creating. This is then processed, by various tools, to produce documentation in accessible formats like

HTML The HyperText Markup Language or HTML is the standard markup language for documents designed to be displayed in a web browser. It can be assisted by technologies such as Cascading Style Sheets (CSS) and scripting languages such as JavaScri ...

and

Rich Text Format ) As an example, the following RTF code would be rendered as follows: This is some bold text. Character encoding A standard RTF file can only consist of 7-bit ASCII characters, but can use escape sequences to encode other characters. Th ...

. The JSDoc specification is released under CC BY-SA 3.0, while its companion

documentation generator A documentation generator is a programming tool that generates software documentation intended for programmers (API documentation) or end users (end-user guide), or both, from a set of source code files, and in some cases, binary files. Some genera ...

and parser library is

free software Free software or libre software is computer software distributed under terms that allow users to run the software for any purpose as well as to study, change, and distribute it and any adapted versions. Free software is a matter of liberty, no ...

under the Apache License 2.0.

History

JSDoc's syntax and semantics are similar to those of the

Javadoc Javadoc (originally cased JavaDoc) is a documentation generator created by Sun Microsystems for the Java language (now owned by Oracle Corporation) for generating API documentation in HTML format from Java source code. The HTML format is used for ...

scheme, which is used for documenting code written in Java. JSDoc differs from Javadoc, in that it is specialized to handle JavaScript's

dynamic Dynamics (from Greek δυναμικός ''dynamikos'' "powerful", from δύναμις ''dynamis'' "power") or dynamic may refer to: Physics and engineering * Dynamics (mechanics) ** Aerodynamics, the study of the motion of air ** Analytical dynam ...

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

Netscape Netscape Communications Corporation (originally Mosaic Communications Corporation) was an American independent computer services company with headquarters in Mountain View, California and then Dulles, Virginia. Its Netscape web browser was onc ...

Mozilla Mozilla (stylized as moz://a) is a free software community founded in 1998 by members of Netscape. The Mozilla community uses, develops, spreads and supports Mozilla products, thereby promoting exclusively free software and open standards, wi ...

project

Rhino A rhinoceros (; ; ), commonly abbreviated to rhino, is a member of any of the five extant species (or numerous extinct species) of odd-toed ungulates in the family Rhinocerotidae. (It can also refer to a member of any of the extinct species o ...

, a JavaScript run-time system written in

Java Java (; id, Jawa, ; jv, ꦗꦮ; su, ) is one of the Greater Sunda Islands in Indonesia. It is bordered by the Indian Ocean to the south and the Java Sea to the north. With a population of 151.6 million people, Java is the world's List ...

. It included a toy "JSDoc" HTML generator, versioned up to 1.3, as an example of its JavaScript capabilities. All main generations of "JSDoc" were headed by micmaths (Michael Mathews). He started with JSDoc.pm in 2001, a simple system written in

Perl Perl is a family of two high-level, general-purpose, interpreted, dynamic programming languages. "Perl" refers to Perl 5, but from 2000 to 2019 it also referred to its redesigned "sister language", Perl 6, before the latter's name was offici ...

, in cooperation with Canadian programmer Gabriel Reid. It was hosted on

SourceForge SourceForge is a web service that offers software consumers a centralized online location to control and manage open-source software projects and research business software. It provides source code repository hosting, bug tracking, mirrorin ...

in a CVS repository. 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 The MIT License is a permissive free software license originating at the Massachusetts Institute of Technology (MIT) in the late 1980s. As a permissive license, it puts only very limited restriction on reuse and has, therefore, high license comp ...

, it was hosted in a Subversion repository on

Google Code Google Developers (previously Google Code) , application programming interfaces (APIs), and technical resources. The site contains documentation on using Google developer tools and APIs—including discussion groups and blogs for developers usin ...

. By 2011 he has refactored the system into JSDoc 3.0 and hosted the result on

GitHub GitHub, Inc. () is an Internet hosting service for software development and version control using Git. It provides the distributed version control of Git plus access control, bug tracking, software feature requests, task management, continuous ...

. It now runs on

Node.js Node.js is an open-source server environment. Node.js is cross-platform and runs on Windows, Linux, Unix, and macOS. Node.js is a back-end JavaScript runtime environment. Node.js runs on the V8 JavaScript Engine and executes JavaScript code o ...

JSDoc tags

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

Example

/** @class Circle representing a circle. */ class Circle /** * Prints a circle. * * @param circle */ function printCircle(circle) Note that the and tags can in fact be omitted: the ECMASyntax is sufficient to make their identities clear, and JSDoc makes use of that. can be automatically deduced as well.

JSDoc in use

* Google's Closure Linter and

Closure Compiler Google Closure Tools is a set of tools to help developers build rich web applications with JavaScript. It was developed by Google for use in their web applications such as Gmail, Google Docs and Google Maps. Closure Compiler The Closure Comp ...

. The latter extracts the type information to optimize its output JavaScript. *

TypeScript TypeScript is a free and open source programming language A programming language is a system of notation for writing computer programs. Most programming languages are text-based formal languages, but they may also be graphical. They are ...

can perform type checking for JavaScript files with JSDoc type annotations. 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'' . *

IntelliJ IDEA IntelliJ IDEA is an integrated development environment (IDE) written in Java (programming language), Java for developing computer software written in Java, Kotlin (programming language), Kotlin, Groovy (programming language), Groovy, and other ...

NetBeans NetBeans is an integrated development environment (IDE) for Java (programming language), Java. NetBeans allows applications to be developed from a set of modular software components called ''modules''. NetBeans runs on Microsoft Windows, Windows, ...

Visual Studio Code Visual Studio Code, also commonly referred to as VS Code, is a source-code editor made by Microsoft with the Electron Framework, for Windows, Linux and macOS. Features include support for debugging, syntax highlighting, intelligent code complet ...

and

RubyMine JetBrains s.r.o. (formerly IntelliJ Software s.r.o.) is a Czech software development company which makes tools for software developers and project managers. , the company has offices in Prague; Munich; Berlin; Boston, Massachusetts; Amsterda ...

understand JSDoc syntax. * Eclipse-based Aptana Studio supports ScriptDoc.
Mozile
the Mozilla Inline Editor uses JSDoc.pm. * Th
Helma
application framework uses JSDoc. * SproutCore documentation was generated using JSDoc

*

Visual Studio Visual Studio is an integrated development environment (IDE) from Microsoft. It is used to develop computer programs including web site, websites, web apps, web services and mobile apps. Visual Studio uses Microsoft software development platfor ...

WebStorm JetBrains s.r.o. (formerly IntelliJ Software s.r.o.) is a Czech software development company which makes tools for software developers and project managers. , the company has offices in Prague; Munich; Berlin; Boston, Massachusetts; Amsterda ...

and many other

Integrated development environment An integrated development environment (IDE) is a software application that provides comprehensive facilities to computer programmers for software development. An IDE normally consists of at least a source code editor, build automation tools a ...

s or

Text Editor A text editor is a type of computer program that edits plain text. Such programs are sometimes known as "notepad" software (e.g. Windows Notepad). Text editors are provided with operating systems and software development packages, and can be us ...

s offer Code Completion and other assistance based on JSDoc comments. * Open source

Atom Every atom is composed of a nucleus and one or more electrons bound to the nucleus. The nucleus is made of one or more protons and a number of neutrons. Only the most common variety of hydrogen has no neutrons. Every solid, liquid, gas, and ...

editor supports JSDoc via th
atom-easy-jsdoc
plugin.

References

External links