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

Question

我目前正在为我工​​作场所使用的 SOAP-webservices 编写 Java-API。
webservice-classes 是用Axis2生成的，它们可以返回null. 因为我不想null在我的业务逻辑级别处理-references，所以我将其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;
    }

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

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

（我知道答案可能是基于意见的，但我没有在 stackoverflow 或通过谷歌搜索找到任何关于此的建议。）

Answer 1

我建议将您的 return 语句 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并且会明白，如果该帐户存在，他需要访问其中的实际信息。

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