Wikipedia

Javadoc: Difference between revisions

Browse history interactively
← Previous edit
Content deleted Content added
VisualWikitext
Converted 1 bare URL web.archive.org archived ref to {{Cite web}}
Tags: Mobile edit Mobile web edit
 
(45 intermediate revisions by 22 users not shown)
Line 1:
{{short description|Documentation generator for Java}}
{{manualhow-to|date=MayAugust 20182023}}
[[File:Javadoc_screenshot.png|thumb|Screenshot]]'''Javadoc''' (originallyalso casedcapitalized as '''JavaDoc''')<ref>Now cased asor 'Javadoc'. See [http://www.oracle.com/technetwork/java/javase/documentation/index-jsp-135444.html]. Originally cased as 'JavaDocjavadoc'. See [http://www.artima.com/intv/jackpot3.html]</ref>'') is aan [[documentationApplication generatorprogramming interface|API]] created by [[Sundocumentation Microsystemsgenerator]] for the [[Java (programming language)|Java programming language]]. (nowBased ownedon byinformation in Java [[Oraclesource Corporationcode]]), forJavadoc generatinggenerates [[Applicationdocumentation programmingformatted interface|API]] documentation inas [[HTML]] formatand fromother formats via [[JavaPlug-in (programming languagecomputing)|Javaextensions]] source code. The HTML format is used for adding the convenience of being able to [[hyperlink]] related documents together.<ref>{{cite web |url=http://agile.csc.ncsu.edu/SEMaterials/tutorials/javadoc/ |title=Archived copyJavadoc |website=agile.csc.ncsu.edu |access-date=12 January 2022 |archive-url=https://web.archive.org/web/20170613233020/http://agile.csc.ncsu.edu/SEMaterials/tutorials/javadoc/ |archive-date=13 June 2017 |url-status=dead}}</ref> Javadoc was created by [[Sun Microsystems]] and is owned by [[Oracle Corporation|Oracle]] today.
 
The "doccontent and formatting of a resulting document are controlled via special [[Markup language|markup]] in source code [[Comment (computer programming)|comments"]]. formatAs this markup is [[de facto standard]] and ubiquitous for documenting Java code,<ref>{{cite web|url = http://docs.oracle.com/javase/1.5.0/docs/tooldocs/solaris/javadoc.html|title = javadoc - The Java API Documentation Generator|access-date = 2011-09-30|publisher = [[Sun Microsystems]]}}.</ref> usedmany by[[Integrated Development Environment|IDE]]s extract and display the Javadoc isinformation while viewing the desource factocode; industryoften standardvia forhover documentingover Javaan classesassociated symbol. Some IDEs, like [[IntegratedIntelliJ DevelopmentIDEA]], Environment[[NetBeans]] and [[Eclipse (software)|IDEEclipse]]s, support generating Javadoc template comment blocks.<ref>[https://www.jetbrains.com/idea/ IntelliJ IDEA], [http://www.netbeans-blog.org/netbeans-ide/generating-javadoc-for-a-project-in-netbeans-ide.html NetBeans] {{Webarchive|url=https://web.archive.org/web/20170405230224/http://www.netbeans-blog.org/netbeans-ide/generating-javadoc-for-a-project-in-netbeans-ide.html |date=2017-04-05 }} and [http://www.eclipse.org/ Eclipse]</ref> likeThe [[IntelliJ<code>@tag</code> IDEA]]syntax of Javadoc markup has been re-used by other documentation generators, including [[NetBeansDoxygen]] and, [[Eclipse (software)|EclipseJSDoc]], automatically generate Javadoc HTML[https://www.erlang.org/doc/apps/edoc/chapter.html Many file editors assist the user in producing Javadoc sourceEDoc] and use the Javadoc info as internal references for the programmer[[HeaderDoc]].
 
Javadoc alsosupports providesextension an API for creatingvia [[doclets]] and taglets, which allowsallow usersfor togenerating analyzedifferent theoutput structureformats and for [[static analysis]] of a Java application[[codebase]]. ThisFor is howexample, [[JDiff]] can generate reports of what changedchanges 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 [[API writer|technical writers]].<ref>{{cite web|url=http://www.artima.com/intv/jackpot3.html
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.
|title=Visualizing with JavaDoc
 
== History ==
Javadoc was an early Java language [[documentation generator]].<ref>{{cite web|url = http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html|title = How to Write Doc Comments for the Javadoc Tool|access-date = 2011-09-30|publisher = [[Sun Microsystems]]}}.</ref> Prior to the use of documentation generators it was customary to use technical writers who would typically write only standalone documentation for the software,<ref>{{cite web|url=http://www.artima.com/intv/jackpot3.html
|title=Visualizing with JavaDoc
|first1=Bill| last1=Venners| first2=James| last2=Gosling | display-authors=etal | publisher=artima.com
|date=2003-07-08
|access-date=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?}}</ref> but it was much harder to keep this documentation in sync with the software itself.
 
Javadoc has been usedpart byof Java since theits first release, and is usuallyoften updated uponwith every neweach release of the [[Java Development Kit]].<ref>{{cite web|url = http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html|title = How to Write Doc Comments for the Javadoc Tool|access-date = 2011-09-30|publisher = [[Sun Microsystems]]}}.</ref>
 
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.
The <code>@field</code> syntax of Javadoc has been emulated by documentation systems for other languages, including the cross-language [[Doxygen]], the [[JSDoc]] system for JavaScript, and Apple's [[HeaderDoc]].
 
== Technical architectureMarkup ==
 
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: <code>/**</code>. A comment block pertains to the symbol that follows the block.
=== Structure of a Javadoc comment ===
A Javadoc comment is set off from code by standard multi-line comment tags <code>/*</code> and <code>*/</code>. The opening tag (called begin-comment delimiter), has an extra asterisk, as in <code>/**</code>.
 
An example of a class header block follows:
# 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 (<code>@param</code>)
## What the method returns (<code>@return</code>)
## Any exceptions the method may throw (<code>@throws</code>)
## Other less-common tags such as <code>@see</code> (a "see also" tag)
 
=== Overview of Javadoc ===
The basic structure of writing document comments is to embed them inside
<code>/** ... */</code>. 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:
 
<syntaxhighlight lang="java">
// import statements
 
/**
* Provides some service
* @author Firstname Lastname <address @ example.com>
* @author Jill Smith <address@example.com>
* @version 1.6 (current version number of program)
* @version 1.6
* @since 1.2 (the version of the package this class was first added to)
* @since 1.2
*/
public class Test {}
// class body
}
</syntaxhighlight>
 
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.
For methods there is (1) a short, concise, one line description to
 
explain what the item does. This is followed by (2) a longer
Various aspects of HTML as supported via Javadoc. For example <code>&lt;p&gt;</code> denotes a paragraph break.
description that may span multiple paragraphs. The details
 
can be explained in full here. This section is
An example of a method header block follows:
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 "<code>&lt;p&gt;</code>" paragraph break tag.
 
<syntaxhighlight lang="java">
/**
* Short one One-line description. (1)
* <p>
* Longer description. If there were any, it would be (2)here.
* here.
* <p>
* And even more explanationsexplanation to follow in consecutive
* paragraphs separated by HTML paragraph breaksbreak.
*
* @param variablevariableName Description text text text. (3)..
* @return Description text text text...
*/
public int methodName (...) { ... }
// method body with a return statement
}
</syntaxhighlight>
 
Variables arecan documentedalso similarlybe to methods with thedocumented. exceptionFor thatexample:
part (3) is omitted. Here the variable contains only the short
description:
 
<syntaxhighlight lang="java">
/**
* Description of the variable here.
*/
private int debug = 0;
</syntaxhighlight>
 
A more complete example follows:
Note that it is not recommended<ref>{{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|access-date=20 Dec 2017}}</ref> 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.
 
<syntaxhighlight lang="java">
/**
* Validates a chess move
* The horizontal and vertical distances of point (x,y)
*
* <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
*/
boolean isValidMove(int fromFile, int fromRank, int toFile, int toRank) { ... }
public int x, y; // AVOID
</syntaxhighlight>
 
Instead, it is recommended to write and document each variable separately:
 
<syntaxhighlight lang="java">
/**
* Moves a chess piece
* The horizontal distance of point.
*
* @see java.math.RoundingMode
*/
void doMove(int fromFile, int fromRank, int toFile, int toRank) { ... }
public int x;
 
/**
* The vertical distance of point.
*/
public int y;
</syntaxhighlight>
 
== Markdown ==
=== Table of Javadoc tags ===
From Java 23 onwards, Javadoc supports the [[Markdown]] standard CommonMark on comment lines that start with <code>///</code> instead of the older multiline format.<ref>https://openjdk.org/jeps/467 {{Bare URL inline|date=August 2025}}</ref>
 
== 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.<ref>{{cite web | url=https://docs.oracle.com/javase/8/docs/technotes/guides/javadoc/doclet/overview.html | title=Doclet Overview }}</ref> A Doclet is written in Java and uses the {{Javadoc:SE|jdk/javadoc/doclet|name=Doclet API|module=jdk.javadoc}},
 
The {{Javadoc:SE|jdk/javadoc/doclet|StandardDoclet|module=jdk.javadoc}}[https://docs.oracle.com/javase/9/javadoc/javadoc-command.htm#JSJAV-GUID-04BFA924-7C45-4E9C-91D1-0B77D97E65AB] included with Javadoc generates [[API]] documentation as frame-based [[HTML]] files. Other Doclets are available on the web {{Citation needed|reason=Is this still true today?|date=December 2017}}, 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 [[Unified Modeling Language|UML]] diagrams generated from the Java classes
 
== Tags ==
{{Update|section|inaccurate=yes|reason=Should be updated according to the [https://docs.oracle.com/en/java/javase/21/docs/specs/javadoc/doc-comment-spec.html official documentation]|date=November 2023}}
Some of the available Javadoc tags<ref>[https://docs.oracle.com/en/java/javase/13/docs/specs/javadoc/doc-comment-spec.html JavaSE 13 Documentation Comment Specification]</ref> are listed in the table below:
 
{| class="wikitable"
!Syntax
!Tag & Parameter
!Usage
!Applies to
!Since
|-
|'''@author''' ''John Smithname''|| DescribesIdentifies anthe 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
|
|-
|'''@version''' ''version''|| ProvidesVersion softwareinformation version|| entry.Module, Max one per Class or Interface. ||Package, Class, Interface, Enum ||
|-
|'''@since''' ''since-text''|| Describes when this functionality has first existed. || Class, Interface, Enum, Field, Method||
|-
|'''@see''' ''reference''|| Provides a linkLinks to other element of documentation. || Class, Interface, Enum, Field, Method||
|-
|'''@param''' ''name description''|| Describes a method parameter. || Method||
|-
|'''@return''' ''description''|| Describes the return value. || Method||
|-
|'''@exception''' ''classname description''<br />'''@throws''' ''classname description''|| Describes an exception that may be thrown from this method.|| Method||
|-
|'''@deprecated''' ''description''|| DescribesMarks an outdatedthe method. as outdated || Class, Interface, Enum, Field, Method||
|-
|{'''@inheritDoc'''}||Copies the description from the overridden method.||Overriding Method||1.4.0
|-
|{'''@link''' ''<var>reference</var>''}||Link to other symbol.||Class, Interface, Enum, Field, Method||
|-
|{'''@linkplain''' ''<var>reference</var>''}
|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
|-
|{'''@code''' ''literal''}|| Formats literal text in the code font. It is; equivalent to <nowiki>'''<code>{@literal}</code></nowiki>.''' || Class, Interface, Enum, Field, Method||1.5.0
|-
|{'''@literal''' ''literal''}|| Denotes literal text.; Thethe enclosed text is interpreted as not containing HTML markup or nested javadoc tags. || Class, Interface, Enum, Field, Method||1.5.0
|-
|{'''@serial''' ''literal''}
|Used in the doc comment forDenotes a default serializable field.
|Field
|
|-
|{'''@serialData''' ''literal''}
|Documents theDenotes data written by the writeObject( ) or writeExternal( ) methods.
|Field, Method
|
|-
|{'''@serialField''' ''literal''}
|DocumentsDenotes 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.
<syntaxhighlight lang="java">
/**
* 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
*/
boolean isValidMove(int fromFile, int fromRank, int toFile, int toRank) {
// ...body
}
 
/**
* Moves a chess piece.
*
* @see java.math.RoundingMode
*/
void doMove(int fromFile, int fromRank, int toFile, int toRank) {
// ...body
}
</syntaxhighlight>
 
== See also ==
* [[Comparison of documentation generators]]
* [[Doxygen]]
* [[C Sharp syntax#XML documentation system|.NET XML documentation comments]]
* [[.NET documentation comments|.NET XML documentation comments]]
 
== References ==
Line 215 ⟶ 174:
* [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]
* [http://globaldocs.info/ Globaldocs: A viewer to browse multiple Javadocs simultaneously.]
* [https://javadoc.allimant.org/ Various Java documentations converted to Windows Help format]
 
[[Category:Free documentation generators]]
[[Category:Source code documentation formats]]
[[Category:Java development tools]]
Retrieved from "https://en.wikipedia.org/wiki/Javadoc"