Parent issue: #19807
Coverage table
Implementation-Independence, Automatic re-use of method comments
Chapter link
Content
Image
Text
Implementation-Independence
Write the description to be implementation-independent, but specifying such dependencies where necessary. This helps engineers write code to be "write once, run anywhere."
As much as possible, write doc comments as an implementation-independent API specification.
Define clearly what is required and what is allowed to vary across platforms/implementations.
Ideally, make it complete enough for conforming implementors. Realistically, include enough description so that someone reading the source code can write a substantial suite of conformance tests. Basically, the spec should be complete, including boundary conditions, parameter ranges and corner cases.
Where appropriate, mention what the specification leaves unspecified or allows to vary among implementations.
If you must document implementation-specific behavior, please document it in a separate paragraph with a lead-in phrase that makes it clear it is implementation-specific. If the implementation varies according to platform, then specify "On " at the start of the paragraph. In other cases that might vary with implementations on a platform you might use the lead-in phrase "Implementation-Specific:". Here is an example of an implementation-dependent part of the specification for java.lang.Runtime:
On Windows systems, the path search behavior of the loadLibrary method is identical to that of the Windows API's LoadLibrary procedure.
The use of "On Windows" at the beginning of the sentence makes it clear up front that this is an implementation note.
Automatic re-use of method comments
You can avoid re-typing doc comments by being aware of how the Javadoc tool duplicates (inherits) comments for methods that override or implement other methods. This occurs in three cases:
When a method in a class overrides a method in a superclass
When a method in an interface overrides a method in a superinterface
When a method in a class implements a method in an interface
In the first two cases, if a method m() overrides another method, The Javadoc tool will generate a subheading "Overrides" in the documentation for m(), with a link to the method it is overriding.
In the third case, if a method m() in a given class implements a method in an interface, the Javadoc tool will generate a subheading "Specified by" in the documentation for m(), with a link to the method it is implementing.
In all three of these cases, if the method m() contains no doc comments or tags, the Javadoc tool will also copy the text of the method it is overriding or implementing to the generated documentation for m(). So if the documentation of the overridden or implemented method is sufficient, you do not need to add documentation for m(). If you add any documentation comment or tag to m(), the "Overrides" or "Specified by" subheading and link will still appear, but no text will be copied.
Guidelines
The first chapter doesn't appear to contain any guideline.
The guideline of the second chapter would need multiple file checking.
Proposal:
| Documentation Comments Rule |
Checkstyle Checks Used |
Sample files |
| 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. |
|
Parent issue: #19807
Coverage table
Implementation-Independence, Automatic re-use of method comments
Chapter link
Content
Image
Text
Implementation-Independence
Write the description to be implementation-independent, but specifying such dependencies where necessary. This helps engineers write code to be "write once, run anywhere."
As much as possible, write doc comments as an implementation-independent API specification.
Define clearly what is required and what is allowed to vary across platforms/implementations.
Ideally, make it complete enough for conforming implementors. Realistically, include enough description so that someone reading the source code can write a substantial suite of conformance tests. Basically, the spec should be complete, including boundary conditions, parameter ranges and corner cases.
Where appropriate, mention what the specification leaves unspecified or allows to vary among implementations.
If you must document implementation-specific behavior, please document it in a separate paragraph with a lead-in phrase that makes it clear it is implementation-specific. If the implementation varies according to platform, then specify "On " at the start of the paragraph. In other cases that might vary with implementations on a platform you might use the lead-in phrase "Implementation-Specific:". Here is an example of an implementation-dependent part of the specification for java.lang.Runtime:
On Windows systems, the path search behavior of the loadLibrary method is identical to that of the Windows API's LoadLibrary procedure.
The use of "On Windows" at the beginning of the sentence makes it clear up front that this is an implementation note.
Automatic re-use of method comments
You can avoid re-typing doc comments by being aware of how the Javadoc tool duplicates (inherits) comments for methods that override or implement other methods. This occurs in three cases:
When a method in a class overrides a method in a superclass
When a method in an interface overrides a method in a superinterface
When a method in a class implements a method in an interface
In the first two cases, if a method m() overrides another method, The Javadoc tool will generate a subheading "Overrides" in the documentation for m(), with a link to the method it is overriding.
In the third case, if a method m() in a given class implements a method in an interface, the Javadoc tool will generate a subheading "Specified by" in the documentation for m(), with a link to the method it is implementing.
In all three of these cases, if the method m() contains no doc comments or tags, the Javadoc tool will also copy the text of the method it is overriding or implementing to the generated documentation for m(). So if the documentation of the overridden or implemented method is sufficient, you do not need to add documentation for m(). If you add any documentation comment or tag to m(), the "Overrides" or "Specified by" subheading and link will still appear, but no text will be copied.
Guidelines
The first chapter doesn't appear to contain any guideline.
The guideline of the second chapter would need multiple file checking.
Proposal: