Javadoc 有明确的规则来记录方法抛出的返回值和异常。但是对于从异步响应(例如 CompletionStage)中返回/抛出的方法,我们应该做些什么呢?或 Future ?
如果我使用 @throws
来记录异步抛出的异常,IDE 会提示该方法不会(直接)抛出异常。没错,方法没有。
如果我在 @return
部分记录了一长串异步抛出的异常,那么生成的文档将很难阅读。
这种情况下的最佳做法是什么?如果可能,请引用已建立的库作为示例。
最佳答案
就其值(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
下记录异常。
结果看起来还不错。
关于asynchronous - 如何记录异步结果、异常?,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/49092824/