Должен ли я писать несколько тегов @return в javadoc

Скажем, у меня есть метод Java, который возвращает массив строк. Внутри метода у меня есть несколько операторов возврата, в зависимости от условий.

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, но думаю, что это не имеет смысла, когда возвращается нуль. Какой способ является лучшей практикой кодирования в целом?


java return code-documentation javadoc
person user3207158    schedule 03.06.2016    source источник
comment
Метод может возвращать только одно значение заданного типа (в вашем случае String[]), поэтому я бы написал один тег @return и описал различные возможные возвращаемые значения.   -  person ujulu    schedule 03.06.2016
comment
Я никогда не видел несколько тегов @return. Правильно ли он отображается на выходе (или, например, показывает только последний)?   -  person Thilo    schedule 03.06.2016
comment
Что произошло, когда вы попытались? Это сработало, как вы ожидали? Я бы удивился, если бы это произошло.   -  person Andreas    schedule 03.06.2016
comment
@Thilo Отображает только первый   -  person user3207158    schedule 03.07.2016
comment
Он отображает только первый @return   -  person user3207158    schedule 03.07.2016

Ответы (2)


arrow_upward
6
arrow_downward

В комментарии Javadoc может быть только один тег @return. 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() {
    ...
}
person Hoopje    schedule 08.06.2016

arrow_upward
4
arrow_downward

У вас может быть только один тег @return в действительном документе Javadoc, и соглашение как это делается частями API, должен был описать, что он возвращает в этой единственной строке.

В вашем случае вы должны указать все три условия.

person Makoto    schedule 03.06.2016