如何记录异步结果、异常？
How to document asynchronous results, exceptions?
Javadoc 有明确的规则来记录 return 值和方法抛出的异常。但是对于来自异步响应（例如 CompletionStage or Future?
中的 return/throw 的方法，我们应该怎么办？
如果我使用 @throws 来记录异步抛出的异常，IDE 会抱怨该方法不会（直接）抛出异常。没错，方法没有。
如果我在 @return 部分记录了一长串异步抛出的异常，则生成的文档将很难阅读。
这种情况的最佳做法是什么？如果可能，请参考已建立的库作为示例。
就其价值而言，我目前正在使用以下语法，但我认为这不是既定的最佳实践：
/**
* @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 下记录异常。
结果看起来还不错。
Javadoc 有明确的规则来记录 return 值和方法抛出的异常。但是对于来自异步响应（例如 CompletionStage or Future?
中的 return/throw 的方法，我们应该怎么办？如果我使用 @throws 来记录异步抛出的异常，IDE 会抱怨该方法不会（直接）抛出异常。没错，方法没有。
如果我在 @return 部分记录了一长串异步抛出的异常，则生成的文档将很难阅读。
这种情况的最佳做法是什么？如果可能，请参考已建立的库作为示例。
就其价值而言，我目前正在使用以下语法，但我认为这不是既定的最佳实践：
/**
* @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下记录异常。
结果看起来还不错。