Javadoc

Javadoc comments have the following form:

/**
 * Describes of the immediately following class, interface,
 * constructor, method, or field. The first sentence is special;
 * it is used as a summary statement.
 *
 * @tag Text for this tag. Tags should go at the end.
 */

Style rules for Javadoc

• Keep comments and code in sync.
• Provide a summary description for each class, interface, field, and method.
  • Write summary descriptions that stand alone.
• Explain how to use your code, not how it works.
  • Describe the programming interface (API).
• Fully describe the signature of each method.
  • Use a @param tags to describe each parameter.
  • Use a @return tag to describe the result (unless it’s void).
  • Use a @throws tags to describe any thrown Exceptions.
• Describe the programming interface before you write the code.
• Do not add parentheses to a method or constructor name unless you want to specify a particular signature.
• Use “this” rather than “the” when referring to instances of the current class.
• Omit the subject in summary descriptions of actions or services.
• Write in the third-person narrative form.
  • Example: "Finds the first blank in the string."
• Include examples if they are helpful.
• Document known defects and deficiencies.
• Use @author and @version tags for your classes and interfaces.

See "The Elements of Java Style" by Allan Vermeulen et al. for more details.

HTML

Javadoc comments are written in HTML. HTML is ordinary text with special tags to indicate typographical effects. Here are some of the basic HTML tags you should know.

<pre>NW   N  NE
     \ | / 
W---+---E
     / | \
SW  S   SE</pre>

NW   N  NE
     \ | / 
W---+---E
     / | \
SW  S   SE

Because the characters '<', '>', and '&' have special meanings in HTML, if you want to put these actual characters in your Javadoc, you have to encode them as follows: