Javadoc Best Practice

https://blog.codefx.org/java/new-javadoc-tags/

* @apiNote This method was added after the interface was released in

*          version 1.0. It is defined as a default method for compatibility

*          reasons. From version 2.0 on, the method will be abstract and

*          all implementations of this interface have to provide their own

*          implementation of the method.

* @implSpec The default implementation will consider each player a winner

*           and return them in an unspecified order.

* @implNote This implementation has linear runtime and does not filter out

*           null players.

https://stackoverflow.com/questions/11671989/best-practice-for-javadocs-interface-implementation-or-both?lq=1

If the implementing method doesn't provide its own Javadoc, there will still be a link to the interface method's docs. I never understood why Eclipse inserts /* (non-Javadoc) @see ... */ as the Javadocs will automatically reference the interface's docs.

The interface should have all the information about the contract, basically what the method does, the description of parameters, return values and so on.

Unless there's some extra information that isn't clear from the interface description (there rarely is), the implementation documentation should then simply link to the interface method

https://engdoc.corp.google.com/eng/doc/devguide/java/style/index.md?cl=head#s7-javadoc
Each paragraph except the first has <p> immediately before the first word, with no space after it
new paragraphs both be introduced with a blank line and be prefixed with <p>.

https://blog.joda.org/2012/11/javadoc-coding-standards.html

Do not use '**/' at the end of the Javadoc.

Use simple HTML tags, not valid XHTML

Define a punchy first sentence

The first sentence, typically ended by a dot, is used in the next-level higher Javadoc. As such, it has the responsibility of summing up the method or class to readers scanning the class or package. To achieve this, the first sentence should be clear and punchy, and generally short.

While not required, it is recommended that the first sentence is a paragraph to itself. This helps retain the punchiness for readers of the source code.

It is recommended to use the third person form at the start. For example, "Gets the foo", "Sets the "bar" or "Consumes the baz". Avoid the second person form, such as "Get the foo".

Use "this" to refer to an instance of the class

When referring to an instance of the class being documented, use "this" to reference it. For example, "Returns a copy of this foo with the bar value updated".

Aim for short single line sentences

Use @link and @code wisely

Many Javadoc descriptions reference other methods and classes. This can be achieved most effectively using the @link and @code features.

The @link feature creates a visible hyperlink in generated Javadoc to the target. The @link target is one of the following forms:

  /**
   * First paragraph.
   * <p>
   * Link to a class named 'Foo': {@link Foo}.
   * Link to a method 'bar' on a class named 'Foo': {@link Foo#bar}.
   * Link to a method 'baz' on this class: {@link #baz}.
   * Link specifying text of the hyperlink after a space: {@link Foo the Foo class}.
   * Link to a method handling method overload {@link Foo#bar(String,int)}.
   */
  public ...

The @code feature provides a section of fixed-width font, ideal for references to methods and class names. While @link references are checked by the Javadoc compiler, @code references are not.

Only use @link on the first reference to a specific class or method. Use @code for subsequent references. This avoids excessive hyperlinks cluttering up the Javadoc.

Define null-handling for all parameters and return types

Whether a method accepts null on input, or can return null is critical information for building large systems. All non-primitive methods should define their null-tolerance in the @param or @return. Some standard forms expressing this should be used wherever possible:

• "not null" means that null is not accepted and passing in null will probably throw an exception , typically NullPointerException
• "may be null" means that null may be passed in. In general the behaviour of the passed in null should be defined
• "null treated as xxx" means that a null input is equivalent to the specified value
• "null returns xxx" means that a null input always returns the specified value

When defined in this way, there should not be an @throws for NullPointerException.

  /**
   * Javadoc text.
   * 
   * @param foo  the foo parameter, not null
   * @param bar  the bar parameter, null returns null
   * @return the baz content, null if not processed
   */
  public String process(String foo, String bar) {...}