Definitive rules by the Book Of Emmanuel are:

• use [...] for omissions
• remove email in @author
• do not use <programlisting role="JAVA" language="JAVA> as we have not introduced the plumbing
• use {@link} for method reference (the first in the JavaDoc of the element) except if it references external classes and if it references the class or element at bay.
• reference methods with () but be careful that some methodname are actually annotation attributes and thus should not have ()
• no import statement
• add package statement
• use <p/> to separate paragraphs but do not use <p>blah blah</p>
• empty line between @doc elements of different types
• something is true but a method returns <literal>true</literal>
• use <ul> for lists
• <li> are indented by 4 spaces compared to <ul>
• multiline @param or @return are indented to align with the beginning of the text of the element

/**
 * @param test This is a long description that needs
 *        to be done on several lines
 */