 | This articlecontainsinstructions or advice. Wikipedia is not a guidebook; please helprewrite such content to be encyclopedic or move it toWikiversity,Wikibooks, orWikivoyage.(August 2023) |
Javadoc (also capitalized asJavaDoc orjavadoc) is anAPIdocumentation generator for theJava programming language. Based on information in Javasource code, Javadoc generates documentation formatted asHTML and other formats viaextensions.[1] Javadoc was created bySun Microsystems and is owned byOracle today.
The content and formatting of a resulting document are controlled via specialmarkup in source codecomments. As this markup isde facto standard and ubiquitous for documenting Java code,[2] manyIDEs extract and display the Javadoc information while viewing the source code; often via hover over an associated symbol. Some IDEs, likeIntelliJ IDEA,NetBeans andEclipse, support generating Javadoc template comment blocks.[3] The@tag syntax of Javadoc markup has been re-used by other documentation generators, includingDoxygen,JSDoc,EDoc andHeaderDoc.
Javadoc supports extension viadoclets and taglets, which allow for generating different output formats and forstatic analysis of acodebase. 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 oftechnical writers.[4]
Javadoc has been part of Java since its first release, and is often updated with each release of theJava 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.
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 presceded 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. */publicintmethodName(Stringinput)throwsException{...}
SomeHTML tags, such as<p>,<head>, and<nav>, as supported in Javadoc.[1]
From Java 23 onwards, Javadoc supports theMarkdown standard CommonMark on comment lines that start with/// instead of the older multiline format.[6]
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 theDoclet API,
TheStandardDoclet[2] included with Javadoc generatesAPI documentation as frame-basedHTML files. Other Doclets are available on the web[citation needed], often for free. These can be used to:
 | This section'sfactual accuracy may be compromised due to out-of-date information. The reason given is: Should be updated according to theofficial documentation. Please help update this article to reflect recent events or newly available information.(November 2023) |
Some of the available Javadoc tags[8] are listed in the table below:
| Syntax | Usage | Applies to | Since |
|---|---|---|---|
| @authorname | Identifies the author such as "Pat Smith" | 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 | Version information | Module, Package, Class, Interface, Enum | |
| @sincesince-text | Describes when this functionality first existed | Class, Interface, Enum, Field, Method | |
| @seereference | Links to other element of documentation | Class, Interface, Enum, Field, Method | |
| @paramname description | Describes a method parameter | Method | |
| @returndescription | Describes the return value | Method | |
| @exceptionclassname description @throwsclassname description | Describes an exception that may be thrown from this method | Method | |
| @deprecateddescription | Marks the method as outdated | 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; equivalent to{@literal} | 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} | Denotes a default serializable field | Field | |
| {@serialDataliteral} | Denotes data written by thewriteObject( ) orwriteExternal( ) methods | Field, Method | |
| {@serialFieldliteral} | Denotes anObjectStreamField component | Field |
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?