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