我应该在javadoc中写多个@return标签

Question

假设我有一个返回字符串数组的java方法.在方法内部,我有多个return语句,具体取决于条件.

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

这个例子可能太天真了.但我的观点是,我应该/可以使用多个@return标签 @return this array if condition 1 is met @return that array if condition 2 is met @return null if condition 3 is met 吗？

我经常写一个单独的@return the login message但是当有一个null返回时认为这没有意义.一般来说哪种方式更好的编码实践？

Answer 1

@return在 Javadoc 注释中只能有一个标签。Javadoc 是为使用您的方法的人编写的。它应该描述方法做什么，而不是它是如何做的。return方法中的语句数量与文档阅读者完全无关，唯一相关的是你的方法为什么输入返回什么。

在您的情况下，您可以例如记录您的示例方法如下：

/** 
 * 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() {
    ...
}