Documentation Comments Style Checkstyle Coverage
Useful information
This coverage report was created for Documentation Comments Style (cached page),
Legend
"???" - Report is incomplete in this line.
"--" - There is no rule in this paragraph.
"↓" - This paragraph is the high-level point of some group.
- Existing Check covers all requirements.
- Existing Check covers some part of requirements.
- Requirements are not possible to check by Checkstyle at all.
Coverage table
ATTENTION: Links to config and sample files in the following table reference to latest (not released yet) config. Config might be slightly different from what we have in the latest release. Please always use config that is embedded to jar or use a custom version copied from one that matches your checkstyle version.
| Documentation Comments Rule | Checkstyle Checks Used | Sample files | |
|---|---|---|---|
 |
Introduction | ↓ | |
| |
Principles | -- | |
| |
Writing API Specifications | -- | |
| |
Java Platform API Specification is defined by the documentation comments in the source code | -- | |
| |
Java Platform API Specification is a contract between callers and implementations | -- | |
| |
Java API Specification assertions need to be implementation-independent | -- | |
| |
Java API Specification should contain assertions sufficient to enable Software Quality Assurance | -- | |
| |
Writing Programming Guide Documentation | -- | |
| |
API spec bugs | -- | |
| |
Code bugs | -- | |
| |
Who Owns and Edits the Doc Comments | -- | |
| |
Terminology | -- | |
| |
Source Files | -- | |
| |
Writing Doc Comments | ↓ | |
| |
Format of a Doc Comment |
InvalidJavadocPosition ( config) JavadocVariable ( config) MissingJavadocMethod ( config) MissingJavadocType ( config) |
samples |
| |
Notes |
CommentsIndentation ( config) JavadocLeadingAsteriskAlign ( config) RequireEmptyLineBeforeBlockTagGroup ( config) JavadocTagContinuationIndentation ( config) LineLength ( config) Guideline that end-comment delimiter should contain only one asterisk is not covered until: #20982. |
samples |
| |
getImage | -- | |
| |
Doc Comment Checking Tool | -- | |
| |
Descriptions | ↓ | |
| |
First Sentence |
SummaryJavadoc ( config) |
samples |
| |
Implementation-Independence | -- | |
| |
Automatic re-use of method comments |
Violations of this guideline cannot be detected by Checkstyle due to its limitation, multiple file checking is not supported. |
|
| |
A Style Guide | ↓ | |
| |
Use <code> style for keywords and names |
Checkstyle cannot reliably cover this requirement because it does not have an English language model to distinguish Java keywords and names used as code references from regular prose. |
|
| |
Use in-line links economically |
Guidelines are not covered until: #19937, #19938. |
|
| |
Omit parentheses for the general form of methods and constructors |
Checkstyle cannot reliably cover this requirement because it is not type-aware and cannot know whether a referenced method or constructor belongs to another class. |
|
| |
OK to use phrases instead of complete sentences | -- | |
| |
Use 3rd person descriptive |
Checkstyle cannot reliably cover this requirement because it requires natural language analysis to determine whether wording is in third person. |
|
| |
Method descriptions begin with a verb phrase |
Checkstyle cannot reliably cover this requirement because it requires natural language analysis. |
|
| |
Class/interface/field descriptions can omit the subject and simply state the object |
Checkstyle cannot reliably cover this requirement because it requires natural language analysis. |
|
| |
Use "this" instead of "the" when referring to an object created from the current class |
Checkstyle cannot reliably cover this requirement because it requires natural language analysis. |
|
| |
Add description beyond the API name |
Checkstyle cannot reliably cover this requirement because it requires natural language analysis to decide whether an API description adds meaningful information beyond the API name. |
|
| |
Be clear when using the term "field" |
Checkstyle cannot reliably cover this requirement because it requires natural language analysis to distinguish the intended meaning of the term field. |
|
| |
Avoid Latin |
Guideline is not covered until: #20987. |
|
| |
Tag Conventions | ↓ | |
|
|
Order of Tags |
AtclauseOrder ( config) |
samples |
| |
Ordering Multiple Tags |
Guideline that multiple @param tags should be listed in argument-declaration order is not covered until: #8990. Guideline that multiple @throws tags should be listed alphabetically by exception name is not covered until: #19698. Guideline that multiple @see tags should be ordered by Javadoc search order is not covered until: #19949. Guideline that multiple @author tags should be listed in chronological order cannot be covered because Checkstyle only sees the latest file content and does not have Git history or other historical class context. |
|
| |
Required Tags |
JavadocMethod ( config) |
samples |
| |
Tag Comments | ↓ | |
| |
@author | -- | |
| |
@version |
Not implemented. The @version SCCS convention is outdated because it was designed for SCCS, before modern version control systems such as Git and others became common. |
|
| |
@param |
NonEmptyAtclauseDescription ( config) JavadocMethod ( config) Guideline that dashes or other punctuation should not be inserted before the description, as the Javadoc tool inserts one dash, is not covered until: #19948. |
samples |
| |
@return |
JavadocMethod ( config) |
samples |
| |
@deprecated | ??? | |
| |
@since | ??? | |
| |
@throws |
JavadocMethod ( config) Cannot cover the guideline that Error should not be documented, as Checkstyle does not have a Check for this yet. See #20792. |
samples |
| |
@see | -- | |
| |
@serial | -- | |
| |
@serialField | -- | |
| |
@serialData | -- | |
| |
{@link} | -- | |
| |
Custom Tags and Annotations |
MissingDeprecated ( config) |
samples |
| |
Documenting Default Constructors |
MissingCtor ( config) Cannot cover compatibility rule for replacing an implicit default constructor, as Checkstyle analyzes only the current source snapshot and cannot know whether the constructor was part of a previously released API. |
samples |
| |
Documenting Exceptions with @throws Tag | -- | |
| |
Documenting Exceptions in API Specs | -- | |
| |
Throws Tag | -- | |
| |
Guidelines - Which Exceptions to Document |
JavadocMethod ( config) Checkstyle cannot distinguish checked from unchecked exceptions due to its limitation: the complete inheritance hierarchy of a type cannot be determined. A dedicated Check could validate differences between exceptions declared in method signatures and exceptions documented in Javadoc @throws tags. Such differences may reveal extra unchecked exceptions declared in signatures, but this validation cannot fully decide which unchecked exceptions should be documented. Not covered until: #20844. |
samples |
| |
Documenting Unchecked Exceptions |
Checkstyle cannot distinguish checked from unchecked exceptions due to its limitation: the complete inheritance hierarchy of a type cannot be determined. A dedicated Check could validate differences between exceptions declared in method signatures and exceptions documented in Javadoc @throws tags. Such differences may reveal extra unchecked exceptions declared in signatures, but this validation cannot fully decide which unchecked exceptions should be documented. Not covered until: #20844. |
|
| |
Background on Checked and Unchecked Exceptions | -- | |
| |
Background on the Throws Clause |
Checkstyle cannot distinguish checked from unchecked exceptions due to its limitation: the complete inheritance hierarchy of a type cannot be determined. A dedicated Check could validate differences between exceptions declared in method signatures and exceptions documented in Javadoc @throws tags. Such differences may reveal extra unchecked exceptions declared in signatures, but this validation cannot fully decide which unchecked exceptions should be documented. Not covered until: #20844. |
|
| |
Package-Level Comments | -- | |
| |
Template for package.html source file |
JavadocPackage ( config) |
samples |
| |
Contents of package.html source file | ??? | |
| |
Documenting Anonymous Inner Classes | -- | |
| |
Including Images | -- | |
| |
Images in Source Tree | ↓ | |
| |
Naming of doc images in source tree |
Not implemented. Sequential numeric image names are not recommended because they create unnecessary renaming and reference updates when images are inserted before existing ones. If somebody needs this, please create a new issue to discuss reasons. |
|
| |
Location of doc images in source tree | -- | |
| |
Images in HTML Destination | ↓ | |
| |
Naming of doc images in HTML destination | -- | |
| |
Location of doc images in HTML destination | -- | |
| |
Examples of Doc Comments | -- | |
| |
Troubleshooting Curly Quotes (Microsoft Word) | -- |
Severity Level
To adjust the default severity level for violations using Checkstyle's Documentation Comments style configuration, set the following system property:
org.checkstyle.doc.comments.severity
For detailed guidance on severity levels, refer to the Severity Level. To configure this property, see the instructions for the CLI's -p option , or use the properties parameter in Ant, or set the Java system property before running Checkstyle.
Suppressions
It is possible to suppress some violations by embedded filters SuppressionFilter, SuppressionXpathFilter, SuppressWithNearbyCommentFilter, SuppressionCommentFilter, SuppressWarningsFilter and SuppressWithNearbyTextFilter.
Location of config file for SuppressionFilter can be defined by system property org.checkstyle.doc.comments.suppressionfilter.config (default value is checkstyle-suppressions.xml).
Location of config file for SuppressionXpathFilter can be defined by system property org.checkstyle.doc.comments.suppressionxpathfilter.config (default value is checkstyle-xpath-suppressions.xml).
To suppress a check in the next line of code using SuppressWithNearbyCommentFilterprecede the line of code with // CHECKSTYLE.SUPPRESS: NameOfTheCheck (replace NameOfTheCheck with the actual check to be suppressed).
To suppress a check on a block of code using SuppressionCommentFilter add // CHECKSTYLE.OFF: NameOfTheCheck before the beginning of the code block and // CHECKSTYLE.ON: NameOfTheCheck after the end of the code block (replace NameOfTheCheck with the actual check to be suppressed).
To suppress a check using SuppressWarningsFilter use Java's@SuppressWarnings({"checkstyle:name_of_the_check", ...}) annotation. Each value passed in the array parameter must meet the format checkstyle:name_of_the_check where the checkstyle: is optional and name_of_the_check is the actual name of check to be suppressed in lowercase format.
To suppress a check for few lines below or above, use SuppressWithNearbyTextFilter suppression, use // CHECKSTYLE.SUPPRESS: NameOfCheck for ([+-]\d+) lines comment. ( replace NameOfCheck with the check you want to suppress. For suppressing a check few lines below, replace ([+-]\d+) with +NumberOfLines where NumberOfLines is number of the lines below from the comment's line number, for suppressing a check few lines above, use "-" instead of "+". )
For more details please review exact configuration of Filters in doc_comments_checks.xml: SuppressionFilter, SuppressionXpathFilter, SuppressWithNearbyCommentFilter, SuppressionCommentFilter, SuppressWarningsFilter, SuppressWithNearbyTextFilter