Javadoc: Difference between revisions

Revision as of 14:44, 6 January 2025

Latest revision as of 01:49, 2 September 2025

(8 intermediate revisions by 4 users not shown)

Line 1:

{{short description|Documentation generator for Java}}

{{how-to|date=August 2023}}

'''Javadoc''' (also capitalized as '''JavaDoc''' or '''javadoc''') is aan [[Application programming interface|API]] [[documentation generator]] for the [[Java (programming language)|Java programming language]]. ItBased generateson information in Java [[Applicationsource programming interface|APIcode]], Javadoc generates documentation informatted as [[HTML]] formatand fromother sourceformats codevia [[Plug-in (computing)|extensions]].<ref>{{cite web |url=http://agile.csc.ncsu.edu/SEMaterials/tutorials/javadoc/ |title=Javadoc |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> ItJavadoc was created by [[Sun Microsystems]] and is owned by [[Oracle Corporation|Oracle]] today.

The Javadoccontent commentand formatformatting of a resulting document are controlled via special [[Markup language|markup]] in source code [[Comment (computer programming)|comments]]. As 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> ismany [[Integrated Development Environment|IDE]]s extract and display the deJavadoc factoinformation standardwhile forviewing documentingthe Javasource classescode; often via hover over an associated 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 templates[https://www.erlang.org/doc/apps/edoc/chapter.html Many file editors assist the user in producing Javadoc sourceEDoc] and show the Javadoc info (via hover over an associated symbol for example) to assist with programming[[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 the performance of a Java executable since comments are ignored by the compiler.

== History ==

Javadoc has been part of Java since its first release, and is often updated with each 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>

Prior to the use of documentation generators, technical writers would often write API documentation that would mismatch the actual source code.<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>

Javadoc has been part of Java since its first release, and is often updated with each 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>

The <code>@tag</code> syntax of Javadoc has been re-used by other documentation generators, including [[Doxygen]], [[JSDoc]], [https://www.erlang.org/doc/apps/edoc/chapter.html EDoc] and [[HeaderDoc]].

Javadoc doesand the source code comments used by Javadoc, do not affect the performance of a Java executable since comments are ignored by the compiler.

== Design ==

== HistoryMarkup ==

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.

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.

An example of a class header block follows:

Line 89 ⟶ 86:

* @see java.math.RoundingMode

*/

void doMove(int fromFile, int fromRank, int toFile, int toRank) { ... }

</syntaxhighlight>

== DesignMarkdown ==

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 ==

Line 164:

== See also ==

* [[Comparison of documentation generators]]

* [[Doxygen]]

* [[.NET documentation comments|.NET XML documentation comments]]