| Documentation comments |
| Documentation comments describe Java classes, interfaces,
constructors, methods, and fields. |
Each doc comment is set inside the comment delimiters
/**...*/, with one comment per class,
interface, or member. This comment should appear just before the declaration:
/**
* The Example class provides ...
*/ public class Example { ... |
Notice that top-level classes and interfaces are not indented, while their members are.
The first line of doc comment (/**) for classes and interfaces is not indented; subsequent
doc comment lines each have 1 space of indentation (to vertically align the asterisks).
Members, including constructors, have 4 spaces for the first doc comment line and 5 spaces
thereafter. |
| If you need to give information about a class, interface, variable, or
method that isn’t appropriate for documentation, use an implementation block
comment or single-line comment immediately after the declaration.
For example, details about the implementation of a class should go in in such an
implementation block comment following the class statement, not in the class doc comment. |
| Doc comments should not be positioned inside a method or constructor
definition block, because Java associates documentation comments with the first
declaration after the comment. |