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

Question

我正在将 C Api 桥接到 Java Api。 C Api 对异常情况使用错误代码。由于每个函数 return 都是这样的错误代码，并且有很多错误代码（大约 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");
        }
    }
}

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

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

我的方法只是调用错误代码句柄 return 从对 C API 的调用中编辑：

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

如果发生错误，该方法将抛出相应的异常。如果没有，它将简单地 return.

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

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

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

Answer 1

在你的 javadoc 中写类似 @throws MyException if underlying service fails 的东西是完全合理的。这在 Java SE 中很常见；例如：

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

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

Javadoc @throws tags for Exceptions thrown by error code handler

java

javadoc

exception