Effective Java

---

ITEM 56: WRITE DOC COMMENTS FOR ALL EXPOSED API ELEMENTS
259
When documenting an annotation type, be sure to document any mem-
bers
as well as the type itself. Document members with noun phrases, as if they
were fields. For the summary description of the type, use a verb phrase that says
what it means when a program element has an annotation of this type:
/**
* Indicates that the annotated method is a test method that
* must throw the designated exception to pass.
*/
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface ExceptionTest {
/**
* The exception that the annotated test method must throw
* in order to pass. (The test is permitted to throw any
* subtype of the type described by this class object.)
*/
Class value();
}
Package-level doc comments should be placed in a file named 
package-
info.java
. In addition to these comments, 
package-info.java
must contain a
package declaration and may contain annotations on this declaration. Similarly, if
you elect to use the module system (Item 15), module-level comments should be
placed in the 
module-info.java
file.
Two aspects of APIs that are often neglected in documentation are thread-
safety and serializability.