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, @trhows group and the other @tag elements
• 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

Here is an example

/**
 * Welcome to this element related to {@link FooBar#baz()}.
 * This allowed 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 {
    [...]
}