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 comment (computer programming), comments, written using a human-readable programming language, usually as plain text. The source code of a Computer program, p ...

files. Using

comments Comment may refer to: * Comment (linguistics) or rheme, that which is said about the topic (theme) of a sentence * Bernard Comment (born 1960), Swiss writer and publisher Computing * Comment (computer programming), explanatory text or informa ...

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 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. T ...

. The JSDoc specification is released under

CC BY-SA 3.0 A Creative Commons (CC) license is one of several public copyright licenses that enable the free distribution of an otherwise copyrighted "work".A "work" is any creative material made by a person. A painting, a graphic, a book, a song/lyrics ...

, 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 gener ...

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, ...

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 ...

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 dyna ...

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 on ...

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, w ...

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 ...

, a JavaScript

run-time system In computer programming, a runtime system or runtime environment is a sub-system that exists both in the computer where a program is created, as well as in the computers where the program is intended to be run. The name comes from the compile t ...

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 mo ...

. 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 programming language, high-level, General-purpose programming language, general-purpose, Interpreter (computing), interpreted, dynamic programming languages. "Perl" refers to Perl 5, but from 2000 to 2019 it ...

, 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, mirrori ...

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 co ...

, 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 usi ...

. 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, co ...

. It now runs on Node.js.

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. The latter extracts the type information to optimize its output JavaScript. *

TypeScript TypeScript is a free and open source programming language developed and maintained by Microsoft. It is a strict syntactical superset of JavaScript and adds optional static typing to the language. It is designed for the development of large appl ...

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 for developing computer software written in Java, Kotlin, Groovy, and other JVM-based languages. It is developed by JetBrains (formerly known as IntelliJ) and is a ...

NetBeans NetBeans is an integrated development environment (IDE) for Java. NetBeans allows applications to be developed from a set of modular software components called ''modules''. NetBeans runs on Windows, macOS, Linux and Solaris. In addition to Java ...

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 compl ...

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; Amsterdam; ...

understand JSDoc syntax. * Eclipse-based

Aptana Studio Aptana, Inc. is a company that makes web application development tools for use with a variety of programming languages (such as JavaScript, Ruby, PHP and Python). Aptana's main products include Aptana Studio, Aptana Cloud and Aptana Jaxer. Aptan ...

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 websites, web apps, web services and mobile apps. Visual Studio uses Microsoft software development platforms such ...

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; Amsterdam; ...

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 u ...

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 ...

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

References

External links