Technical architecture Structure of a Javadoc comment Overview of Javadoc Table of Javadoc tags Examples
See also
References
External links
{{manual|date=May 2018}}Javadoc (originally cased JavaDoc)[1] 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 adding the convenience of being able to hyperlink related documents together.[2]
The "doc comments" format[3] used by Javadoc is the de facto industry standard for documenting Java classes. Some IDEs,[4] like IntelliJ IDEA, NetBeans and Eclipse, automatically generate Javadoc HTML. 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 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.[5] Prior to the use of documentation generators it was customary to use technical writers who would typically write only standalone documentation for the software,[6] 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.
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 is written next to the items
without any separating newline. Note that any import statements must precede the class declaration. The class declaration usually
contains:
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.
Variables are documented similarly to methods with the exception that
part (3) is omitted. Here the variable contains only the short
description:
Note that it is not recommended[7] 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.
Instead, it is recommended to write and document each variable separately:
Table of Javadoc tags
Some of the available Javadoc tags[8] are listed in the table below:
Tag & Parameter
Usage
Applies to
Since
@authorJohn Smith
Describes an author.
Class, Interface, Enum
{@docRoot}
Represents the relative path to the generated document's root directory from any generated page.
Class, Interface, Enum, Field, Method
@versionversion
Provides software version entry. Max one per Class or Interface.
Class, Interface, Enum
@sincesince-text
Describes when this functionality has first existed.
Class, Interface, Enum, Field, Method
@seereference
Provides a link to other element of documentation.
Describes an exception that may be thrown from this method.
Method
@deprecateddescription
Describes an outdated method.
Class, Interface, Enum, Field, Method
{@inheritDoc}
Copies the description from the overridden method.
Overriding Method
1.4.0
{@linkreference}
Link to other symbol.
Class, Interface, Enum, Field, Method
{@linkplainreference}
Identical to {@link}, except the link's label is displayed in plain text than code font.
Class, Interface, Enum, Field, Method
{@value#STATIC_FIELD}
Return the value of a static field.
Static Field
1.4.0
{@codeliteral}
Formats literal text in the code font. It is equivalent to <code>{@literal}</code>.
Class, Interface, Enum, Field, Method
1.5.0
{@literalliteral}
Denotes literal text. The enclosed text is interpreted as not containing HTML markup or nested javadoc tags.
Class, Interface, Enum, Field, Method
1.5.0
{@serialliteral}
Used in the doc comment for a default serializable field.
Field
{@serialDataliteral}
Documents the data written by the writeObject( ) or writeExternal( ) methods.
Field, Method
{@serialFieldliteral}
Documents an ObjectStreamField component.
Field
Examples
An example of Javadoc to document a method follows. Notice that spacing and number of characters in this example are as conventions state.
See also
Comparison of documentation generators
.NET XML documentation comments
References
1. ^Now cased as 'Javadoc'. See . Originally cased as 'JavaDoc'. See 2. ^https://web.archive.org/web/20170613233020/http://agile.csc.ncsu.edu/SEMaterials/tutorials/javadoc/ 3. ^{{cite web|url = http://docs.oracle.com/javase/1.5.0/docs/tooldocs/solaris/javadoc.html|title = javadoc - The Java API Documentation Generator|accessdate = 2011-09-30|publisher = Sun Microsystems}}. 4. ^[https://www.jetbrains.com/idea/ IntelliJ IDEA], NetBeans and Eclipse 5. ^{{cite web|url = http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html|title = How to Write Doc Comments for the Javadoc Tool|accessdate = 2011-09-30|publisher = Sun Microsystems}}. 6. ^{{cite web|url=http://www.artima.com/intv/jackpot3.html |title=Visualizing with JavaDoc |author=Bill Venners, James Gosling....|publisher=artima.com|date=2003-07-08|accessdate=2013-01-19|quote=When I did the original JavaDoc in the original compiler, even the people close around me pretty soundly criticized it. And it was interesting, because the usual criticism was: a good tech writer could do a lot better job than the JavaDoc does. And the answer is, well, yeah, but how many APIs are actually documented by good tech writers? And how many of them actually update their documentation often enough to be useful?}} 7. ^{{cite news|title=Java Platform, Standard Edition Tools Reference for Oracle JDK on Solaris, Linux, and OS X, Release 8. Section "Multiple-Field Declarations"|url=https://docs.oracle.com/javase/8/docs/technotes/tools/unix/javadoc.html#JSSOR650|accessdate=20 Dec 2017}} 8. ^[https://docs.oracle.com/javase/8/docs/technotes/tools/unix/javadoc.html#CHDBEFIF Javadoc tags in JavaSE 6]
External links
[https://docs.oracle.com/javase/9/javadoc/javadoc.htm Java Platform, Standard Edition Javadoc Guide]
[https://www.jcp.org/en/jsr/detail?id=260 JSR 260] Javadoc Tag Technology Update Java Specification Request (defines new Javadoc tags)
[https://web.archive.org/web/20130927133806/https://today.java.net/pub/a/today/2004/08/26/ashkelon.html Improve on Javadoc with ashkelon]
Globaldocs: A viewer to browse multiple Javadocs simultaneously.
[https://javadoc.allimant.org/ Various Java documentations converted to Windows Help format]
2 : Free documentation generators|Java development tools