Methods

Rule 8:Write doc comment for all exported API element

Follow the tips to make doc comment more readable:

1. The first “sentence” of each doc comment (as defined below) becomes the summary description of the element to which the comment pertains.
   The summary description must stand on its own to describe the functionality of the element it summarizes. To avoid confusion,
   no two members or constructors in a class or interface should have the same summary description.

the summary description should be a verb phrase (including any object) describing the action performed by the method. For example:
• ArrayList(int initialCapacity)—Constructs an empty list with the specified
initial capacity.
• Collection.size()—Returns the number of elements in this collection

For classes, interfaces, and fields, the summary description should be a noun phrase describing the thing represented by an instance of the class or interface or
by the field itself. For example:
• Instant—An instantaneous point on the time-line.
• Math.PI—The double value that is closer than any other to pi, the ratio of the
circumference of a circle to its diameter.

2.Be careful if the intended summary description contains a period, because the period can prematurely terminate the description. For example, a doc comment that begins with the phrase “A college degree, such as B.S., M.S. or Ph.D.” will result in the summary description “A college degree, such as B.S., M.S.”
The problem is that the summary description ends at the first period that is followed by a space, tab, or line terminator.
The best solution is to surround the offending period and any associated text with an {@literal}

3.Two aspects of APIs that are often neglected in documentation are threadsafety and serializability.
Whether or not a class or static method is threadsafe, you should document its thread-safety level