Content deleted Content added
Stevebroshar (talk | contribs) →Design: This section is not really about design; not in typical meanings of design; renaming to markup |
Tags: Mobile edit Mobile web edit |
||
| (3 intermediate revisions by 3 users not shown) | |||
Line 1:
{{short description|Documentation generator for Java}}
{{how-to|date=August 2023}}
'''Javadoc''' (also capitalized as '''JavaDoc''' or '''javadoc''') is an [[Application programming interface|API]] [[documentation generator]] for the [[Java (programming language)|Java programming language]]. Based on information in Java [[source code]], Javadoc generates documentation formatted as [[HTML]] and other formats via [[Plug-in (computing)|extensions]]
The content and formatting 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> many [[Integrated Development Environment|IDE]]s extract and display the Javadoc information while viewing the source code; often via hover over an associated symbol. Some IDEs,
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.
Line 12:
|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
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: <code>/**</code>. A comment block pertains to the symbol that follows the block.
An example of a class header block follows:
Line 86:
* @see java.math.RoundingMode
*/
void doMove(int fromFile, int fromRank, int toFile, int toRank)
</syntaxhighlight>
== Markdown ==
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 161 ⟶ 164:
== See also ==
* [[Comparison of documentation generators]]
* [[Doxygen]]
* [[.NET documentation comments|.NET XML documentation comments]]
| |||