java - 为返回类型 'Optional' 编写 Javadoc

Question

我目前正在为工作场所使用的 SOAP Web 服务编写 Java-API。
Web 服务类是使用 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;
    }

上述方法执行 Web 服务操作以在数据库中搜索某些帐户记录。如果没有找到具有匹配参数的帐户 accountId ，方法调用response.getAccount()可返回null .

是否有更简洁的方式来编写 @return 的 Javadoc ？
特别是对于短语“包装为可选<>”？

(我知道答案可能是基于意见的，但我还没有在 stackoverflow 或谷歌搜索上找到任何对此的建议。)

Answer 1

为什么不说jdk是怎么做的呢？例如Stream::reduce:

@return an {@link Optional} describing the result of the reduction

在你的情况下，它是:

an Optional describing the account.