Parent issue: #19807
Coverage table
Notes
Chapter link
Content
Image
Text
- The resulting HTML from running Javadoc is shown below
- Each line above is indented to align with the code below the comment.
- The first line contains the begin-comment delimiter ( /**).
- Starting with Javadoc 1.4, the leading asterisks are optional.
- Write the first sentence as a short summary of the method, as Javadoc automatically places it in the method summary table (and index).
- Notice the inline tag {@link URL}, which converts to an HTML hyperlink pointing to the documentation for the URL class. This inline tag can be used anywhere that a comment can be written, such as in the text following block tags.
- If you have more than one paragraph in the doc comment, separate the paragraphs with a
<p> paragraph tag, as shown.
- Insert a blank comment line between the description and the list of tags, as shown.
- The first line that begins with an "@" character ends the description. There is only one description block per doc comment; you cannot continue the description following block tags.
- The last line contains the end-comment delimiter ( */) Note that unlike the begin-comment delimiter, the end-comment contains only a single asterisk.
For more examples, see Simple Examples.
So lines won't wrap, limit any doc-comment lines to 80 characters.
Guidelines
| Status |
Guideline |
Check Coverage |
Notes |
| 🟢 Covered |
Each line of the comment is indented to align with the code below the comment |
CommentsIndentation
JavadocLeadingAsteriskAlign |
This is enforced through a combination of checks. CommentsIndentation ensures that the Javadoc comment block is aligned with the surrounding code, while JavadocLeadingAsteriskAlign enforces alignment of the leading * on each line. Together, the two checks cover both aspects of the guideline. |
| 🟢 Covered |
Empty line between the description and the list of tags |
RequireEmptyLineBeforeBlockTagGroup |
RequireEmptyLineBeforeBlockTagGroup enforces the presence of a blank line before the block tag section. |
| 🟢 Covered |
There is only one description block per doc comment; you cannot continue the description following block tags |
JavadocTagContinuationIndentation |
JavadocTagContinuationIndentation enforces the indentation of continuation lines in Javadoc block tags. This matches the Javadoc tool behaviour: once the block tag section begins, later text is treated as part of the corresponding block tag description, not as a new free-standing description block. Therefore, text placed after block tags is handled as tag continuation text and must follow the expected continuation indentation. |
| 🔴 Missing |
The last line contains the end-comment delimiter (*/) Note that unlike the begin-comment delimiter, the end-comment contains only a single asterisk |
Missing |
There is currently no check ensuring that the closing delimiter uses exactly one asterisk. As a result, invalid forms such as **/ may be accepted. |
| 🟢 Covered |
Limit any doc-comment lines to 80 characters |
LineLength |
This can be enforced with LineLength by setting max to 80 and using ignorePattern to ignore lines that do not look like Javadoc comment lines. For example: <property name="ignorePattern" value="^(?!\s*\*).*$"/>. This checks lines starting with *, while ignoring ordinary code lines. |
Parent issue: #19807
Coverage table
Notes
Chapter link
Content
Image
Text
<p>paragraph tag, as shown.For more examples, see Simple Examples.
So lines won't wrap, limit any doc-comment lines to 80 characters.
Guidelines
JavadocLeadingAsteriskAlign
CommentsIndentationensures that the Javadoc comment block is aligned with the surrounding code, whileJavadocLeadingAsteriskAlignenforces alignment of the leading*on each line. Together, the two checks cover both aspects of the guideline.RequireEmptyLineBeforeBlockTagGroupenforces the presence of a blank line before the block tag section.JavadocTagContinuationIndentationenforces the indentation of continuation lines in Javadoc block tags. This matches the Javadoc tool behaviour: once the block tag section begins, later text is treated as part of the corresponding block tag description, not as a new free-standing description block. Therefore, text placed after block tags is handled as tag continuation text and must follow the expected continuation indentation.*/) Note that unlike the begin-comment delimiter, the end-comment contains only a single asterisk**/may be accepted.LineLengthby settingmaxto80and usingignorePatternto ignore lines that do not look like Javadoc comment lines. For example:<property name="ignorePattern" value="^(?!\s*\*).*$"/>. This checks lines starting with*, while ignoring ordinary code lines.