Sollte ich mehrere @ Return-Tags in Javadoc schreiben

Question

Angenommen, ich habe eine Java-Methode, die ein Array von Zeichenfolgen zurückgibt. Innerhalb der Methode habe ich mehr als eine Return-Anweisung, abhängig von den Bedingungen.

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; 
} 

Dieses Beispiel ist vielleicht zu naiv. Aber mein Punkt ist, sollte/kann ich mehrere @ return-Tags verwenden, wie @return this array if condition 1 is met @return that array if condition 2 is met @return null if condition 3 is met ?

Ich schreibe oft eine einzige @return the login message, aber denke, das macht weniger Sinn, wenn es eine Nullrückgabe gibt. Welcher Weg ist generell eine bessere Kodierung?

Answer 1

Sie können nur einen einzigen @return Tag in einem Javadoc-Kommentar haben. Javadoc ist für die Person geschrieben, die Ihre Methode verwendet. Es sollte beschreiben was die Methode tut, nicht wie es tut es. Die Anzahl der return Anweisungen in der Methode ist für den Dokumentationsleser völlig irrelevant, die einzige relevante Sache ist, was Ihre Methode für welche Eingaben zurückgibt.

In Ihrem Fall könnten Sie zum Beispiel Ihr beispielhaftes Verfahren dokumentieren, wie folgt:

/** 
* 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

Sie können nur ein @return Tag in gültigem Javadoc haben, und die Konvention as done by parts of the API wurde beschrieben, was es in dieser einzelnen Zeile zurückgibt.

Für Ihren Fall würden Sie alle drei Bedingungen angeben.