Javadoc (originally cased JavaDoc) is a
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 ...
created by
Sun Microsystems
Sun Microsystems, Inc. (Sun for short) was an American technology company that sold computers, computer components, software, and information technology services and created the Java programming language, the Solaris operating system, ZFS, the ...
for the
Java language
Java is a high-level, class-based, object-oriented programming language that is designed to have as few implementation dependencies as possible. It is a general-purpose programming language intended to let programmers ''write once, run any ...
(now owned by
Oracle Corporation
Oracle Corporation is an American multinational computer technology corporation headquartered in Austin, Texas. In 2020, Oracle was the third-largest software company in the world by revenue and market capitalization. The company sells da ...
) for generating
API
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 ...
documentation in
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 ...
format from
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 ...
source code. The HTML format is used for adding the convenience of being able to
hyperlink
In computing, a hyperlink, or simply a link, is a digital reference to data that the user can follow or be guided by clicking or tapping. A hyperlink points to a whole document or to a specific element within a document. Hypertext is text wit ...
related documents together.
The "doc comments" format used by Javadoc is the de facto industry standard for documenting Java classes. Some
IDEs, like
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, ...
and
Eclipse
An eclipse is an astronomical event that occurs when an astronomical object or spacecraft is temporarily obscured, by passing into the shadow of another body or by having another body pass between it and the viewer. This alignment of three ce ...
, automatically generate Javadoc templates. Many file editors assist the user in producing Javadoc source and use the Javadoc info as internal references for the programmer.
Javadoc also provides an API for creating
doclets
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 fo ...
and taglets, which allows users to analyze the structure of a Java application. This is how JDiff can generate reports of what changed between two versions of an API.
Javadoc does not affect performance in Java as all comments are removed at compilation time. Writing comments and Javadoc is for better understanding the code and thus better maintaining it.
History
Javadoc was an early Java language
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 ...
. Prior to the use of documentation generators it was customary to use technical writers who would typically write only standalone documentation for the software, but it was much harder to keep this documentation in sync with the software itself.
Javadoc has been used by Java since the first release, and is usually updated upon every new release of the
Java Development Kit
The Java Development Kit (JDK) is a distribution of Java Technology by Oracle Corporation. It implements the Java Language Specification (JLS) and the Java Virtual Machine Specification (JVMS) and provides the Standard Edition (SE) of the Java ...
.
The
@field
syntax of Javadoc has been emulated by documentation systems for other languages, including the cross-language
Doxygen
Doxygen ( ) is a documentation generator and static analysis tool for software source trees. When used as a documentation generator, Doxygen extracts information from specially-formatted comments within the code. When used for analysis, Doxyge ...
, the
JSDoc
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 ...
system for JavaScript, and Apple's
HeaderDoc
HeaderDoc is a documentation generator developed and maintained by Apple Inc. Using specially commented source code files as input, HeaderDoc generates documentation for the code in HTML or XML format. Syntax for HeaderDoc comment tags is largel ...
.
Technical architecture
Structure of a Javadoc comment
A Javadoc comment is set off from code by standard multi-line comment tags
/*
and
*/
. The opening tag (called begin-comment delimiter), has an extra asterisk, as in
/**
.
# The first paragraph is a description of the method documented.
# Following the description are a varying number of descriptive tags, signifying:
## The parameters of the method (
@param
)
## What the method returns (
@return
)
## Any exceptions the method may throw (
@throws
)
## Other less-common tags such as
@see
(a "see also" tag)
Overview of Javadoc
The basic structure of writing document comments is to embed them inside
/** ... */
. The Javadoc comment block is positioned immediately above the items
without any separating newline. Note that any import statements must precede the class declaration. The class declaration usually
contains:
// import statements
/**
* @author Firstname Lastname
* @version 1.6 (current version number of program)
* @since 1.2 (the version of the package this class was first added to)
*/
public class Test
For methods there is (1) a short, concise, one line description to
explain what the item does. This is followed by (2) a longer
description that may span multiple paragraphs. The details
can be explained in full here. This section is
optional. Lastly, there is (3) a tag section to list the accepted input
arguments and return values of the method. Note that all of the
Javadoc is treated as HTML so the multiple paragraph sections
are separated by a "
<p>
" paragraph break tag.
/**
* Short one line description. (1)
*
* Longer description. If there were any, it would be (2)
* here.
*
* And even more explanations to follow in consecutive
* paragraphs separated by HTML paragraph breaks.
*
* @param variable Description text text text. (3)
* @return Description text text text.
*/
public int methodName (...)
Variables are documented similarly to methods with the exception that
part (3) is omitted. Here the variable contains only the short
description:
/**
* Description of the variable here.
*/
private int debug = 0;
Note that it is not recommended to define multiple variables in a single documentation comment. This is because Javadoc reads each variable and places them separately to the generated HTML page with the same documentation comment that is copied for all fields.
/**
* The horizontal and vertical distances of point (x,y)
*/
public int x, y; // AVOID
Instead, it is recommended to write and document each variable separately:
/**
* The horizontal distance of point.
*/
public int x;
/**
* The vertical distance of point.
*/
public int y;
Table of Javadoc tags
Some of the available Javadoc tags are listed in the table below:
Examples
An example of Javadoc to document a method follows. Notice that spacing and number of characters in this example are as conventions state.
/**
* Validates a chess move.
*
* Use to move a piece.
*
* @param fromFile file from which a piece is being moved
* @param fromRank rank from which a piece is being moved
* @param toFile file to which a piece is being moved
* @param toRank rank to which a piece is being moved
* @return true if the move is valid, otherwise false
* @since 1.0
*/
boolean isValidMove(int fromFile, int fromRank, int toFile, int toRank)
/**
* Moves a chess piece.
*
* @see java.math.RoundingMode
*/
void doMove(int fromFile, int fromRank, int toFile, int toRank)
Doclets
Doclet programs work with the Javadoc tool to generate documentation from code 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 ...
.
Doclets are written in the Java programming language and use the to:
* Select which content to include in the documentation
* Format the presentation of the content
* Create the file that contains the documentation
Th
included with Javadoc generates
API
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 ...
documentation as frame-based
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 ...
files. Many non-standard doclets are available on the web , often for free. These can be used to:
* Create other non-API types of documentation
* Output the documentation to other non-HTML file types such as
PDF
Portable Document Format (PDF), standardized as ISO 32000, is a file format developed by Adobe in 1992 to present documents, including text formatting and images, in a manner independent of application software, hardware, and operating systems. ...
* Output the documentation as HTML with additional features such as a search or with embedded
UML
The Unified Modeling Language (UML) is a general-purpose, developmental modeling language in the field of software engineering that is intended to provide a standard way to visualize the design of a system.
The creation of UML was originally m ...
diagrams generated from the Java classes
See also
*
Comparison of documentation generators
The following tables compare general and technical information for a number of documentation generators. Please see the individual products' articles for further information. Unless otherwise specified in footnotes, comparisons are based on the s ...
*
.NET XML documentation comments
References
{{Reflist
External links
Java Platform, Standard Edition Javadoc GuideJSR 260Javadoc Tag Technology Update
Java Specification Request
The Java Community Process (JCP), established in 1998, is a formalized mechanism that allows interested parties to develop standard technical specifications for Java technology. Anyone can become a JCP Member by filling a form available at thJCP w ...
(defines new Javadoc tags)
Improve on Javadoc with ashkelonGlobaldocs: A viewer to browse multiple Javadocs simultaneously.Various Java documentations converted to Windows Help format
Free documentation generators
Java development tools