|
=== Overview of Javadoc ===
Most Javadoc comments are imbedded inside
The basic structure of writing document comments is to embed them inside
<code>/** ... */</code> tags. The Javadoc comment block is positioned immediately above the items
without any separating newline., Noteand thatbelow any import statements must precede the class declaration. The class declaration usually
contains:
</syntaxhighlight>
ForDocumentation methodscomments therefor methods isusually (1)contain a short, concise, one line description to
explain what the item does. This is, followed by (2) a longer description, and lastly a tag section that lists accepted input arguments and return values of the method. The
Javadoc is treated as HTML, so a "<code><p></code>" paragraph break tag can be used to denote multiple paragraphs.
description that may span multiple paragraphs. The details
can be explained in full here. This section is
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><p></code>" paragraph break tag.
<syntaxhighlight lang="java">
</syntaxhighlight>
Variables are documented similarly to methods, withbut often lack the exceptiontags at the end of the thatcomment.
part (3) is omitted. Here the variable contains only the short
description:
<syntaxhighlight lang="java">
</syntaxhighlight>
Note that itIt 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, becauseas 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">
=== Examples ===
An example of Javadoc to document a method follows. Notice that spacing and number of characters in this example are as conventions state{{Clarify|date=September 2024}}.
<syntaxhighlight lang="java">
/**
| 