Javadoc
Page Module:Message box/ambox.css has no content.
 | This article contains instructions or advice. (August 2023) |
Javadoc (also capitalized as JavaDoc or javadoc) is an API documentation generator for the Java programming language. Based on information in Java source code, Javadoc generates documentation formatted as HTML and other formats via extensions.[1] Javadoc was created by Sun Microsystems and is owned by Oracle today.
The content and formatting of a resulting document are controlled via special markup in source code comments. As this markup is de facto standard and ubiquitous for documenting Java code,[2] many IDEs extract and display the Javadoc information while viewing the source code, often via hover over an associated symbol. Some IDEs, like IntelliJ IDEA, NetBeans and Eclipse, support generating Javadoc template comment blocks.[3] The @tag syntax of Javadoc markup has been re-used by other documentation generators, including Doxygen, JSDoc, EDoc and HeaderDoc.
Javadoc supports extension via doclets and taglets, which allow for generating different output formats and for static analysis of a codebase. For example, JDiff reports changes between two versions of an API.
Although some criticize Javadoc and API document generators in general, one motivation for creating Javadoc was that more traditional (less automated) API documentation is often out-of-date or does not exist due to business constraints such as limited availability of technical writers.[4]
Javadoc has been part of Java since its first release, and is often updated with each release of the Java Development Kit.[5]
Javadoc and the source code comments used by Javadoc, do not affect the performance of a Java executable since comments are ignored by the compiler.
Markup
Javadoc ignores comments unless they are specially marked. A Javadoc comment is marked with an extra asterisk after the start of a multi-line comment: /**. Following lines are preceded with an *, and the entire comment block should be terminated with a */.
An example of a method Javadoc comment follows:
/**
* Description of what the method does.
*
* @param input Description of parameter.
* @return Description of return value.
* @throws Exception Description of exception.
*/
public int methodName(String input) throws Exception { ... }
Some HTML tags, such as <p>, <head>, and <nav>, are supported in Javadoc.[1]
Markdown
From Java 23 onwards, Javadoc supports the Markdown standard CommonMark on comment lines that start with /// instead of the older multiline format.[6]
Doclets
A Doclet program works with Javadoc to select which content to include in the documentation, format the presentation of the content and create the file that contains the documentation.[7] A Doclet is written in Java and uses the Doclet API,
The StandardDoclet[2] included with Javadoc generates API documentation as frame-based HTML files. Other Doclets are available on the web [citation needed], often for free. These can be used to:
- Create other types of documentation (non-API)
- Output to a format other than HTML, such as PDF
- Output as HTML with additional features such as a search or with embedded UML diagrams generated from the Java classes
Tags
Page Module:Message box/ambox.css has no content.
[[File:Template:Ambox globe current red|42px|link=|alt=]] | This section's factual accuracy may be compromised due to out-of-date information. The reason given is: Should be updated according to the official documentation. (November 2023) |
Some of the available Javadoc tags[8] are listed in the table below:
| Syntax | Usage | Applies to | Since |
|---|---|---|---|
| Page Template:Mono/styles.css has no content.@author name | Identifies the author such as "Pat Smith" | Class, Interface, Enum | |
| Page Template:Mono/styles.css has no content.{@docRoot} | Represents the relative path to the generated document's root directory from any generated page | Class, Interface, Enum, Field, Method | |
| Page Template:Mono/styles.css has no content.@version version | Version information | Module, Package, Class, Interface, Enum | |
| Page Template:Mono/styles.css has no content.@since since-text | Describes when this functionality first existed | Class, Interface, Enum, Field, Method | |
| Page Template:Mono/styles.css has no content.@see reference | Links to other element of documentation | Class, Interface, Enum, Field, Method | |
| Page Template:Mono/styles.css has no content.@param name description | Describes a method parameter | Method | |
| Page Template:Mono/styles.css has no content.@return description | Describes the return value | Method | |
| Page Template:Mono/styles.css has no content.@exception classname description @throws classname description |
Describes an exception that may be thrown from this method | Method | |
| Page Template:Mono/styles.css has no content.@deprecated description | Marks the method as outdated | Class, Interface, Enum, Field, Method | |
| Page Template:Mono/styles.css has no content.{@inheritDoc} | Copies the description from the overridden method | Overriding Method | 1.4.0 |
| Page Template:Mono/styles.css has no content.{@link reference} | Link to other symbol | Class, Interface, Enum, Field, Method | |
| Page Template:Mono/styles.css has no content.{@linkplain reference} | Identical to {@link}, except the link's label is displayed in plain text than code font
|
Class, Interface, Enum, Field, Method | |
| Page Template:Mono/styles.css has no content.{@value #STATIC_FIELD} | Return the value of a static field | Static Field | 1.4.0 |
| Page Template:Mono/styles.css has no content.{@code literal} | Formats literal text in the code font; equivalent to {@literal} |
Class, Interface, Enum, Field, Method | 1.5.0 |
| Page Template:Mono/styles.css has no content.{@literal literal} | 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 |
| Page Template:Mono/styles.css has no content.{@serial literal} | Denotes a default serializable field | Field | |
| Page Template:Mono/styles.css has no content.{@serialData literal} | Denotes data written by the writeObject( ) or writeExternal( ) methods
|
Field, Method | |
| Page Template:Mono/styles.css has no content.{@serialField literal} | Denotes an ObjectStreamField component
|
Field |
See also
References
Page Template:Reflist/styles.css has no content.
- ^ Page Module:Citation/CS1/styles.css has no content."Javadoc". agile.csc.ncsu.edu. Archived from the original on 13 June 2017. Retrieved 12 January 2022.
- ^ Page Module:Citation/CS1/styles.css has no content."javadoc - The Java API Documentation Generator". Sun Microsystems. Retrieved 2011-09-30..
- ^ IntelliJ IDEA, NetBeans Script error: No such module "webarchive". and Eclipse
- ^ Page Module:Citation/CS1/styles.css has no content.Venners, Bill; Gosling, James; et al. (2003-07-08). "Visualizing with JavaDoc". artima.com. Retrieved 2013-01-19.
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?
- ^ Page Module:Citation/CS1/styles.css has no content."How to Write Doc Comments for the Javadoc Tool". Sun Microsystems. Retrieved 2011-09-30..
- ^ Page Module:Citation/CS1/styles.css has no content."JEP 467: Markdown Documentation Comments". OpenJDK. 2023-09-11. Retrieved 2025-09-10.
- ^ Page Module:Citation/CS1/styles.css has no content."Doclet Overview".
- ^ JavaSE 13 Documentation Comment Specification
External links
- Javadoc Tool Home Page
- Java Platform, Standard Edition Javadoc Guide
- JSR 260 Javadoc Tag Technology Update Java Specification Request (defines new Javadoc tags)
- Improve on Javadoc with ashkelon
- Various Java documentations converted to Windows Help format
