How to write Javadoc for a getInstance method?

Question

Say I have something like this:

public class MyClass {
    private static MyClass sInstance;

    /**
     *
     * @return The {@link MyClass} application instance.
     */
    public static MyClass getInstance() {
        return sInstance;
    }
}

IntelliJ gives me this warning:

'@link' pointing to containing class is unnecessary

What's the proper/conventional way to write this piece of Javadoc?

How would you write it?

Answer 1

In the JDK, they use {@code} . That does not make a clickable link, but you are already looking at the page that would be linked anyway.

For example (from String.java ):

  /**
  * Initializes a newly created {@code String} object so that it represents
  * the same sequence of characters as the argument; in other words, the
  * newly created string is a copy of the argument string. Unless an
  * explicit copy of {@code original} is needed, use of this constructor is
  * unnecessary since Strings are immutable.
  *
  * @param  original
  *         A {@code String}
  */

Answer 2

You only get the warning because the link won't go anywhere. Just change it to {@code MyClass} to keep the formatting but without the link.

Here are some example getInstance() methods from the JDK.

java.text.Collator :

/**
 * Gets the Collator for the current default locale.
 * The default locale is determined by java.util.Locale.getDefault.
 * @return the Collator for the default locale.(for example, en_US)
 * @see java.util.Locale#getDefault
 */
public static synchronized Collator getInstance() {

java.text.NumberFormat :

/**
 * Returns a general-purpose number format for the current default
 * {@link java.util.Locale.Category#FORMAT FORMAT} locale.
 * This is the same as calling
 * {@link #getNumberInstance() getNumberInstance()}.
 *
 * @return the {@code NumberFormat} instance for general-purpose number
 * formatting
 */
public final static NumberFormat getInstance() {