如何记录异步结果，异常? [英] How to document asynchronous results, exceptions?

问题描述

Javadoc有明确的规则来记录返回值和方法抛出的异常.但是我们应该如何处理从异步响应中返回/抛出的方法，例如未来?

Javadoc has clear rules for documenting the return value and exceptions thrown by a method. But what are we supposed to do for methods that return/throw from within an asynchronous response such as CompletionStage or Future?

如果我使用@throws记录异步引发的异常，则IDE会抱怨该方法没有(直接)引发异常.是的，该方法不正确.

If I use @throws to document exceptions that are thrown asynchronously, the IDE complains that the method doesn't throw the exceptions (directly). And it is right, the method does not.

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

If I document the long list of exceptions that are thrown asynchronously in the @return section the resulting documentation is difficult to read.

在这种情况下，最佳做法是什么?如有可能，请参考已建立的库作为示例.

What is the best practice for this situation? If possible, please reference established libraries as examples.

推荐答案

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

For what it's worth, I'm currently using the following syntax but I don't think it is an established best practice:

/**
 * @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下记录文档异常.

• Throw all exceptions asynchronously, even for instant failures like argument preconditions. This allows clients to centralize error handling in one place.
• Document exceptions under the @return using the same @throws syntax that is familiar to developers.

结果看起来还不错.

这篇关于如何记录异步结果，异常?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！