Написание Javadoc для типа возврата «Необязательно <T>» - PullRequest
Новая
       38

Написание Javadoc для типа возврата «Необязательно <T>»

2 голосов
/ 05 июля 2019

В настоящее время я пишу Java-API для SOAP-веб-сервисов, используемых на моем рабочем месте.
Классы веб-сервиса генерируются с Axis2 и могут возвращать null. Поскольку я не хочу иметь дело с null -референциями на моем уровне бизнес-логики, я использую Optional<> в качестве типа возврата.
Например: 

/**
 * Reads account-data to given accountId. 
 * 
 * @param accountId
 *          the primary key of table 'account'
 * @return  the account wrapped as an Optional<>, if an account with primary key 'accountId' exists; Optional.empty(), else
 */
public Optional<Account> readAccount(long accountId) throws RemoteException, ServiceFaultException {
        // prepare SOAP-Request
        ReadAccount request = new ReadAccount();
        request.setAccountId(accountId);

        // execute SOAP-Request
        ReadAccountResponse response = accountService.readAccount(request);

        // process Response
        Optional<Account> account = Optional.ofNullable(response.getAccount());

        return account;
    }

Приведенный выше метод выполняет веб-сервисную операцию для поиска некоторой учетной записи в базе данных. Если не найдено ни одной учетной записи с соответствующим аргументом accountId, вызов метода response.getAccount() может вернуть null.

Есть ли более краткий способ написания Javadoc для @return?
Специально для фразы "завернутый как дополнительный <>"?

(Я знаю, что ответы могут быть основаны на мнениях, но я не нашел никаких рекомендаций для этого по стеку или поиску.)

Ответы [ 2 ]

2 голосов
/ 05 июля 2019

Почему бы не сказать это, как делает JDK? Например Stream::reduce:

@ вернуть {@link Необязательно}, описывающий результат сокращения

В вашем случае это будет:

Необязательное описание учетной записи.

0 голосов
/ 05 июля 2019

Я бы предложил упростить ваш javadoc оператора return следующим образом: 

/**
 * Reads account-data to given accountId. 
 * 
 * @param accountId
 *          the primary key of table 'account'
 * @return the account wrapped in an {@link Optional}
 */
public Optional<Account> readAccount(long accountId) throws RemoteException, ServiceFaultException {
  // function here
}

причина этого в том, что Optional.empty() является ожидаемой и неизменной частью Optional API;каждый разработчик, который знает, что такое Optional, будет знать, что следует ожидать пустой Optional, если учетная запись отсутствует;и поймет, что ему нужен доступ к актуальной информации внутри Optional, если учетная запись присутствует.

Мы предоставляем здесь @link, чтобы позволить разработчикам, которые не слышали о Optional s, посмотреть вверхего соответствующий Javadoc и понять, как это работает;само по себе это не обязательно, но может быть полезно, если над вашим проектом работает много менее опытных разработчиков.

...