如何记录函数可能抛出的所有异常？

Question

如果你有一个可能抛出异常的公共函数，它使用其他（私有或公共）辅助函数也可能抛出异常，我认为你应该记录公共函数可以抛出哪些异常，这包括由辅助函数。

类似这样的东西（使用 Doxygen）：

/** 
 * @throw Exception ...
 * @throw ExceptionThrownByHelper ...
 * @throw ExceptionThrownByHelpersHelper ...
 */
void theFunction() 
{ 
    helperWhichMayThrowException();
}

而helperWhichMayThrowException() 还调用了其他可能引发异常的函数。

为此，您可以：

1. 递归跟踪所有函数theFunction() 调用并查找该函数抛出的异常。这是一项繁重的工作，当您向帮助程序添加异常时，您可能会忘记在某处记录异常。
2. 在theFunction() 中捕获助手抛出的所有异常并转换它们，这样您就可以确定只抛出您指定的异常。但是为什么要使用异常呢？
3. 不用担心辅助函数抛出的异常，但是您不能对所有异常进行单元测试，因为您不知道公共函数会抛出哪些异常
4. 有一些工具可以（半）自动列出助手等抛出的所有异常。我查看了 Doxygen 的文档，但没有找到执行此操作的方法。

我想使用选项 4，但我还没有找到好的解决方案，也许使用 Doxygen 可行？或者我只是想记录太多？？？

编辑：也许它不是很清楚，但我正在寻找一种简单的方法来记录函数可能抛出的所有异常（最好使用 Doxygen），而无需手动检查所有辅助函数。一种简单的方法包括“不记录所有异常”或“捕获并转换theFunction() 中的所有异常”

Answer 1

从根本上说，在现实世界的几乎所有情况下，您所要求的都是不可能的。

记录抛出的异常有两个部分。

1) 简单一点。记录在您的方法中直接引发的异常。您可以手动执行此操作，但这非常费力，并且如果您未能使文档与代码保持同步，则文档会产生误导（可能比根本没有文档更糟糕，因为您只能真正信任您确定的文档是 100% 准确的）。我的AtomineerUtils 加载项使这更容易实现，因为它以最少的工作使代码和文档集保持同步。

2) 不可能的位。记录所有可能“通过”您的方法的异常。这意味着通过您的方法调用的方法的整个子树进行递归，以查看它们可能会抛出什么。为什么不可能？好吧，在最简单的情况下，您将静态绑定到已知方法，因此可以扫描它们以查看它们抛出的内容 - 相当容易。但是大多数情况最终会调用动态绑定的方法（例如，虚拟方法、反射或 COM 接口、dll 中的外部库方法、操作系统 API 等），您无法确定可能会抛出什么（因为您不会知道在您实际在最终用户的 PC 上运行程序之前调用什么 - 每台 PC 都不同，在（例如）WinXP 和 Win7 上执行的代码可能完全不同。或者想象你调用了一个虚拟方法，然后有人添加了一个插件-in 到您的程序中，该程序会覆盖该方法并引发一种新类型的异常）。可靠地处理这种情况的唯一方法是在您的方法中捕获所有异常，然后重新抛出可以精确记录的特定异常 - 如果您不能这样做，那么异常的文档几乎仅限于“通常在您的方法中抛出和通常预期的异常”，使“异常错误”基本上没有记录，并简单地传递到更高级别的未处理异常捕获块。 （正是这种可怕的“未定义”异常行为通常导致使用 catch(...) 的必要性 - 从学术上讲，它是“邪恶的”，但如果你希望你的程序是防弹的，你有时必须使用 catch - 确保意外情况不会影响您的应用程序）。

Answer 2

我想出了以下手动解决方案。基本上我只是从我打电话的成员那里复制@throw 文档。如果 Doxygen 有一个类似于@copydoc 的@copythrows，那就太好了，但以下方法会起作用：

class A {
    public:
        /** @defgroup A_foo_throws
         *
         * @throws FooException
         */

        /** 
         * @brief Do something.
         *
         * @copydetails A_foo_throws
         */
        void foo();
};

class B {
    public:
        // This group contains all exceptions thrown by B::bar()
        // Since B::bar() calls A::foo(), we also copy the exceptions
        // thrown by A::foo().

        /** @defgroup B_bar_throws
         *
         * @copydetails A_foo_throws
         * @throws BarException
         */

        /**
         * @brief Do something else.
         *
         * @copydetails B_bar_throws
         */
        void bar();
};  

然后在Doxyfile配置文件中添加*_throws到EXCLUDE_SYMBOLS。这样可以确保这些组不会显示为模块。

然后B::bar() 生成此文档：

void B::bar()
做点别的吧。

例外情况：
FooException
异常：
酒吧异常