Definitive rules by the Book Of Emmanuel are:

• use [...] for omissions, prefer it on a dedicated line rather than inlined. For declaration, use a ; after {{User user = [...];}}
• remove email in @author
• use @author on non inner classes or interfaces
• 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 ()
  - in the spec use <methodname>Foo.bar()</methodname> and in the JavaDoc {@link Foo#bar()}
  - no import statement
  - add package statement
  - use <p/> to separate paragraphs but do not use <p>blah blah</p>
  - empty line between the @param, @return, @throws group and the other @tag elements
  - @throws does not use {@link } for the exception
  - import classes used by {@link} and @throws exceptions so that the unqualified name works
• 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
• The core of the JavaDoc uses capital letters and punctuation like in plain English
• @tag attributes do not use capital letters for the beninning of a sentence nor use dots in the end, prefer ; to separate sentences in this situation
• Use verbs at the third person instead of the imperative tense (?!): Returns foo instead of Return foo.

Here is an example

/**
 * Returns the complementary elements related to {@link FooBar#baz()}.
 * This allows to break things apart.
 * <p/>
 * Demolition mileage may vary depending on the robustness
 * of {@code FooBar} when using {@code List}:
 * <ul>
 *     <li>This is a beginning</li>
 *     <li>This is the end</li>
 * </ul>
 *
 * @param test this is a long description that needs
 *        to be done on several lines, yep
 * @param foo this is another param
 * @return the result
 * @throws {@code IllegalArgumentException} when things happen
 *
 * @since 1.1
 * @deprecated
 */
public void someMethod() {
    User user = [...];
    [...]
}

/**
 * Welcome to this element related to {@link FooBar}.
 * This allowed to break things apart.
 * <p/>
 * Demolition mileage may vary depending on the robustness
 * of {@code FooBar} when using {@code List}
 *
 * @author Emmanuel Bernard
 * @since 1.1
 * @deprecated
 */
public class GoodStuff {
    [...]
}