• The first sentence of each doc comment should be a summary sentence
• Write the description to be implementation-independent, but specifying such dependencies where necessary. (what is required, what is allowed)
• wrap keywords in <code>...</code>

## typical meta annotations

• @author is not critical, because it is not included when generating the API specification
• @version SCCS string "%I%, %G%", which converts to something like “ 1.39, 02/28/97” (mm/dd/yy) when the file is checked out of SCCS
• @since specify the product version when the Java name was added to the API specification (if different from the implementation)

## typical method definition

• @param parameter-name description
• followed by the name (not data type) of the parameter, followed by a description of the parameter
• the first noun in the description is the data type
• @return description
• omit for methods that return void and for constructors
• include it for all other methods, even if its content is entirely redundant with the method description
• @throws class-name description should be included for any checked exceptions (previously, it was @exception)

• {@value package.class#field}
• when {@value} is used (without any argument) in the doc comment of a static field, it displays the value of that constant: The value of this constant is {@value}.
• otherwise it displays the value of the specified constant: Evaluates the script starting with {@value #SCRIPT_START}.
• {@code text}
• Equivalent to <code>{@literal}</code>.

• @see reference
• Adds a "See Also" heading
• reference is a string: Adds a text entry for string. No link is generated. The string is a book or other reference to information not available by URL.
• reference is an <a href="URL#value">label</a>: Adds a link as defined by URL#value. The URL#value is a relative or absolute URL.
• reference is an package.class#member label: Adds a link (with optional visible text label) that points to the documentation for the specified name in the Java Language that is referenced.
• {@link package.class#member label}
• in-line link with visible text label that points to the documentation for the specified package, class or member name of a referenced class
• not necessary to add links for all API names in a doc comment
• @serial (or @serialField or @serialData) for interoperability with alternative implementations of a Serializable class and to document class evolution

## deprecation

• @deprecated deprecated-text
• the first sentence should at least tell the user when the API was deprecated and what to use as a replacement
• a {@link} tag should be included that points to the replacement method