Classes are documented

[whs]

All classes and methods should be documented with Javadoc.

A Javadocs guideline/standard should be decided before starting this task.

[whs]

Here are some points we should apply from the Google's Java Style Guide

• Use full style only

/**
 * Multiple lines of Javadoc text are written here,
 * wrapped normally...
 */
public int method(String p1) { ... }

• For every paragraphs but the first one there is always an empty blank line preceeding it. That line should contains only an asterisk.
• For every paragraphs but the first one there is a preceeding <p> before the first word. There must be no space after it.

/**
 * First paragraph goes here
 *
 * <p>Second paragraph goes here
 *
 * @param p1 Description of p1 goes here
 */
public int method(String p1) { ... }

• Write the @ clauses in this order: @author, @param, @return, @throws, @deprecated. If you use it, it must be followed by a description. If the description does not fit on a single line, the next line should be indented by 4 spaces.
• Every public class and public or protected members of that class must be documented.
  • For obvious cases it could be omitted (for example, in a getter/setter). If it use a technical term, the term should be explained in Javadocs.
  • Overriding method may have no Javadocs.

[whs]

Here are some points we should apply from Oracle's How to Write Doc Comment:

• When mentioning Java keywords, package names, class names, method names, field names, argument names and code example wrap them in <code>...</code>
• Use {@link} only for the first occurence of that term.
• Don't {@link} to well known packages such as java.lang
• OK to use phrases instead of complete sentences.
• The first sentence of each doc comment should be a summary sentence, containing a concise but complete description of the API item. This means the first sentence of each member, class, interface or package description.
• Use 3rd person.
  • Yes: Gets the label
  • No: Get the label
• Method description begins with a verb phrase
  • Yes: Gets the label of this button.
  • No: This method gets the label of this button.
• Omit the subject if possible
  • Yes: A button label
  • No: This field is a button label
• Use "this" instead of "the" when referring to an object created from the current class.
  • Yes: Gets the toolkit for this component.
  • No: Gets the toolkit for the component.
• Don't just repeat the method name in sentence form.
• Don't use aka, e.g., i.e., viz. Use their meaning instead.

Tags

• Order @author by time. The creater of the class appears on top.
• @param is required for all parameters
• @return is always specified for methods not returning void even if it is the same as the method description.
• @throws may list unchecked exceptions. It may not be the complete list of exceptions, however.