错误代码处理程序抛出的异常的 Javadoc @throws 标记

Question

我正在将 C Api 桥接到 Java Api。 C Api 对异常情况使用错误代码。由于每个函数都会返回这样的错误代码，并且有很多错误代码(大约 100 个)，因此我编写了一个错误代码处理程序，它将错误代码转换为一堆更通用的运行时异常:

public class ErrorCodeHandler {
    public static void handle(int status) {
        switch(status) {
            case SUCCESS:
                return; // In case of success, simply return
            case NO_VALID_DATA:
                throw new DataError("No valid data");
            ...
            case NO_CONNECTION:
                throw new ConnectionError("No connection");
        }
    }
}

我的所有自定义异常类都继承自特定于我的应用程序的基本异常类:

public class MyException extends RuntimeException { ... }
public class DataException extends MyException { ... }
...

我的方法只是对调用 C API 返回的错误代码调用句柄:

public void someMethod() {
    int status = cBinding.someMethod();
    ErrorCodeHandler.handle(status);
}

如果发生错误，该方法将抛出适当的异常。如果没有，它将简单地返回。

现在我面临着如何记录这种异常处理的问题。我读到您没有将运行时异常添加为 throws 子句，而是使用 Javadoc @throws 标记对其进行记录。

现在我的问题是，我是否应该为我知道可以从方法抛出的每个不同异常添加一个 @throws 标记(通过查找可能的错误代码间接)，或者我应该只记录一个通用的 @throws MyException？我觉得第一种方法会使我的文档变得困惑，其中包含大量几乎无用的 @throws 标签(其中很多错误代码非常罕见)，并且记录这些内容将需要付出很大的努力。第二种方法主要是复制粘贴，但我会失去异常层次结构给我的优势。

有人做过类似的事情吗？关于如何记录此类内容有什么建议吗？

Answer 1

在 javadoc 中编写类似 @throws MyException if底层服务失败 的内容是完全合理的。这在 Java SE 中相当常见；例如:

• Files.copy尽管它可以抛出 IOException 的许多其他子类，但只有 IOException 和 IOException 的两个子类的 @throws 子句。
• JDBC 方法 Statement.execute具有 SQLException 的 @throws 子句和 SQLException 的一个子类，尽管可以抛出 SQLException 的许多其他子类。