asynchronous - 如何记录异步结果、异常？

Question

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

如果我使用 @throws 来记录异步抛出的异常，IDE 会提示该方法不会(直接)抛出异常。没错，方法没有。

如果我在 @return 部分记录了一长串异步抛出的异常，那么生成的文档将很难阅读。

这种情况下的最佳做法是什么？如果可能，请引用已建立的库作为示例。

Answer 1

就其值(value)而言，我目前正在使用以下语法，但我认为这不是既定的最佳实践:

/**
 * @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);

我的指导方针如下:

• 异步抛出所有异常，即使是像参数前提条件这样的即时失败。这允许客户将错误处理集中在一个地方。
• 使用开发人员熟悉的相同 @throws 语法在 @return 下记录异常。

结果看起来还不错。