为返回类型“Optional<T>”编写 Javadoc

Question

我目前正在为我工作场所使用的 SOAP 网络服务编写 Java-API。Web 服务类是使用Axis2生成的，它们可以返回null. 因为我不想null在我的业务逻辑级别处理 -references，所以我使用Optional<>as 返回类型。例如：/** * 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？特别是对于短语“wrapped as an Optional<>”？

Answer 1

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

@return 一个描述归约结果的{@link Optional}

在您的情况下，它将是：

描述帐户的可选。

Answer 2

我建议将您的返回语句 javadoc 简化为以下内容：

/**

 * 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()是 API 的预期且不变的部分Optional；每个知道 anOptional是什么的开发人员都知道，如果帐户丢失，则期望一个空的 Optional；Optional如果帐户存在，他将理解他需要访问内部的实际信息。

我们在这里提供一个@link，让没有听说过Optionals的开发者可以查阅它各自的javadoc，了解它是如何工作的；这本身不是强制性的，但如果有很多经验不足的开发人员参与您的项目，这可能会有所帮助。