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

我正在将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标记（这些错误代码中的很多非常罕见）将我的文档弄得乱七八糟，并且记录这些错误代码需要付出很大的努力。第二种方法主要是复制粘贴，但我将失去异常层次结构给我的优势

---

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

在javadoc中编写类似于

@throws MyException（如果底层服务失败）

，这是完全合理的。这在JavaSE中相当常见；例如：

• 只有IOException的

  @throws

  子句和IOException的两个子类，即使它可以抛出IOException的许多其他子类
• JDBC方法有一个SQLException的

  @throws

  子句和一个子类SQLException，尽管还有许多其他子类可以抛出

---

关于如何记录此类资料有什么建议吗？-我们在这里谈论javadocs是的，我会添加标签！不管怎样，我在代码中这样做了，看起来每个方法/函数都可以抛出所有异常，是这样吗？通常方法/函数抛出异常子集。如果从C API返回正确的错误代码，则可以抛出异常子集。在实践中，函数只返回特定的错误代码。然后，我将做同样的事情，并记录可能出现的一般异常和特定异常。