Should I write multiple @return tags in javadoc

Question

Say I have a java method that returns an array of strings. Inside the method, I have more than one return statements, depending on conditions.

public String[] userLogIn() {
    String[] success = {"You", "are", "the", "king"};
    String[] errorMsg = {"You", "are", "nothing"};
    double ran = Math.random();
    if(ran < 0.33)
        return success;
    else if (ran < 0.66)
        return errorMsg;
    else
        return null;
}

This example might be too naive. But my point is, should/can I use multiple @return tags, like @return this array if condition 1 is met @return that array if condition 2 is met @return null if condition 3 is met ?

I often write one single @return the login message but think this makes less sense when there is a null return. Which way is a better coding practice in general?

Answer 1

You can only have a single @return tag in a Javadoc comment. Javadoc is written for the person using your method. It should describe what the method does, not how it does it. The number of return statements in the method is compeletely irrelevant to the documentation reader, the only relevant thing is what your method returns for what inputs.

In your case, you could for example document your example method as follows:

/** 
 * Logs in the user.
 *
 * @return the result of the operation if the logging in is successful, or
 *         an error message describing the failure if it is not
 */
public String[] userLogIn() {
    ...
}

Answer 2

You can only have one @return tag in valid Javadoc, and the convention as done by parts of the API has been to describe what it returns in that single line.

For your case, you would specify all three conditions.