如何记录异步结果，异常？

Question

Javadoc有明确的规则来记录方法引发的返回值和异常。但是我们应该对从CompletionStage或Future等异步响应中返回/抛出的方法做些什么呢？

如果我使用@throws来记录异步抛出的异常，IDE会抱怨该方法不会抛出异常（直接）。它是对的，方法没有。

如果我记录了@return部分中异步抛出的长异常列表，则难以阅读生成的文档。

这种情况的最佳做法是什么？如果可能，请参考已建立的图书馆作为示例。

Answer 1

对于它的价值，我目前正在使用以下语法，但我认为这不是一个既定的最佳实践：

/**
 * @param symbol the name of a stock ticker
 * @return the price of the ticker
 * <br> {@code @throws NullPointerException} if {@code symbol} is null
 * <br> {@code @throws IOException} if an I/O error occurs
 */
public CompletionStage<BigDecimal> getPrice(String symbol);

我的指引如下：

• 异步抛出所有异常，即使对于参数前置条件等即时失败也是如此。这允许客户在一个地方集中错误处理。
• 使用开发人员熟悉的相同@return语法记录@throws下的例外情况。

结果看起来相当不错。