This article contains instructions, advice, or how-to content .(August 2023) |
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 via extensions, other formats. [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.
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: /**
. A comment block pertains to the symbol that follows the block.
An example of a class header block follows:
/** * Provides some service * @author Jill Smith <address@example.com> * @version 1.6 * @since 1.2 */publicclassTest{}
For a method, the first line is a short description of the method. If more detail is warranted, then it may be followed by a longer description in additional paragraphs. Following that are optionally various tags.
Various aspects of HTML as supported via Javadoc. For example <p>
denotes a paragraph break.
An example of a method header block follows:
/** * One-line description * <p> * Longer description. If there were any, it would be here. * <p> * And even more explanation to follow in consecutive * paragraphs separated by paragraph break. * * @param variableName Description... * @return Description... */publicintmethodName(...){...}
Variables can also be documented. For example:
/** * Description of the variable here */privateintdebug=0;
A more complete example follows:
/** * Validates a chess move * * <p>Use {@link #doMove(int fromFile, int fromRank, int toFile, int toRank)} 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 */booleanisValidMove(intfromFile,intfromRank,inttoFile,inttoRank){...}/** * Moves a chess piece * * @see java.math.RoundingMode */voiddoMove(intfromFile,intfromRank,inttoFile,inttoRank){...}
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. [6] A Doclet is written in Java and uses the Doclet API
,
The StandardDoclet
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:
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 [7] 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 the writeObject( ) or writeExternal( ) methods | Field, Method | |
{@serialFieldliteral} | Denotes an ObjectStreamField component | Field |
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 anywhere (WORA), meaning that compiled Java code can run on all platforms that support Java without the need to recompile. Java applications are typically compiled to bytecode that can run on any Java virtual machine (JVM) regardless of the underlying computer architecture. The syntax of Java is similar to C and C++, but has fewer low-level facilities than either of them. The Java runtime provides dynamic capabilities that are typically not available in traditional compiled languages.
An HTML element is a type of HTML document component, one of several types of HTML nodes. The first used version of HTML was written by Tim Berners-Lee in 1993 and there have since been many versions of HTML. The current de facto standard is governed by the industry group WHATWG and is known as the HTML Living Standard.
Doxygen is a documentation generator that works with many programming languages. It extracts information from specially-formatted source code comments and saves the information in one of various supported formats.
Code or text folding, or less commonly holophrasting, is a feature of some graphical user interfaces that allows the user to selectively hide ("fold") or display ("unfold") parts of a document. This allows the user to manage large amounts of text while viewing only those subsections that are currently of interest. It is typically used with documents which have a natural tree structure consisting of nested elements. Other names for these features include expand and collapse, code hiding, and outlining. In Microsoft Word, the feature is called "collapsible outlining".
ROBODoc is a documentation tool similar to Javadoc and licensed under the GPL. It is used to extract API documentation from source code. It can be used with any language that supports comments and works by extracting specially formatted headers. These are then reformatted into HTML, DocBook, TROFF, ASCII, LaTeX, PDF, or RTF.
Plain Old Documentation (pod) is a lightweight markup language used to document the Perl programming language as well as Perl modules and programs.
JDiff is a Javadoc doclet which generates an HTML report of all the packages, classes, constructors, methods, and fields which have been removed, added or changed in any way, including their documentation, when two Java APIs are compared. Which can be used to described exactly what has changed between the two releases of a product. Only the API of each version is compared. It does not compare what the source code does when executed.
Natural Docs is a multi-language documentation generator. It is written in C# and available as free software under the terms of the AGPL. It attempts to keep the comments written in source code just as readable as the generated documentation. It is written and maintained by Greg Valure.
PHPDoc is an adaptation of Javadoc format for the PHP programming language. It is still an informal standard for commenting PHP code, but it is in the process of being formalized. It allows external document generators like phpDocumentor, which is the de facto standard implementation, to generate documentation of APIs and helps some IDEs such as Zend Studio, NetBeans, JetBrains PhpStorm, ActiveState Komodo Edit and IDE, PHPEdit and Aptana Studio to interpret variable types and other ambiguities in the loosely typed language and to provide improved code completion, type hinting and debugging.
XML Interface for Network Services (XINS) is an open-source technology for definition and implementation of internet applications, which enforces a specification-oriented approach.
The Java Modeling Language (JML) is a specification language for Java programs, using Hoare style pre- and postconditions and invariants, that follows the design by contract paradigm. Specifications are written as Java annotation comments to the source files, which hence can be compiled with any Java compiler.
Ddoc is a documentation generation technology for the D programming language; provided as a feature of the D compiler. Ddoc is similar to other documentation generation technologies such as Doxygen and Javadoc.
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 largely similar to, and as of HeaderDoc version 8, supportive of Javadoc tags. HeaderDoc 8.7 and later also provides partial support for many Doxygen tags. Apple's HeaderDoc project is free, open source software distributed under the Apple Public Source License.
In the Java computer programming language, an annotation is a form of syntactic metadata that can be added to Java source code. Classes, methods, variables, parameters and Java packages may be annotated. Like Javadoc tags, Java annotations can be read from source files. Unlike Javadoc tags, Java annotations can also be embedded in and read from Java class files generated by the Java compiler. This allows annotations to be retained by the Java virtual machine at run-time and read via reflection. It is possible to create meta-annotations out of the existing ones in Java.
Sandcastle is a documentation generator from Microsoft. It automatically produces MSDN-style code documentation out of reflection information of .NET assemblies and XML documentation comments found in the source code of these assemblies. It can also be used to produce user documentation from Microsoft Assistance Markup Language (MAML) with the same look and feel as reference documentation.
In computer programming, a comment is text embedded in source code that a translator ignores. Generally, a comment is an annotation intended to make the code easier for a programmer to understand – often explaining an aspect that is not readily apparent in the symbolic (non-comment) code.
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, by various tools, to produce documentation in accessible formats like HTML and Rich Text Format. The JSDoc specification is released under CC BY-SA 3.0, while its companion documentation generator and parser library is free software under the Apache License 2.0.
VSdocman is a documentation generator that allows for code commenting and the automatic generation of technical documentation from C# and VB .NET projects. It is directly integrated in Visual Studio as an extension.
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 Application Programming Interface (API). It is derivative of the community driven OpenJDK which Oracle stewards. It provides software for working with Java applications. Examples of included software are the Java virtual machine, a compiler, performance monitoring tools, a debugger, and other utilities that Oracle considers useful for Java programmers.
Yesod is a web framework based on the programming language Haskell for productive development of type-safe, representational state transfer (REST) model based, high performance web applications, developed by Michael Snoyman, et al. It is free and open-source software released under an MIT License.
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?