如何记录一个函数可能抛出的所有异常？ [英] How to document all exceptions a function might throw?

问题描述

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

If you have a public function which may throw an exception which uses other (private or public) helper functions which can also throw exceptions I think you should document what exceptions the public function can throw and this includes exceptions thrown by the helper functions.

这样的东西（使用Doxygen）：

Something like this (using Doxygen):

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

和 helperWhichMayThrowException（）

and helperWhichMayThrowException() also calls other functions which may throw exceptions.

要执行此操作，您可以：

To do this you can:

1. 递归地跟随所有函数 theFunction（）调用并查找该函数抛出的异常。


2. 在 theFunction（）函数中捕获所有被帮助者抛出的异常，这是一个很大的工作，你可能会忘记在某个地方记录一个异常。 ）并转换它们，所以你确保只有指定的异常被抛出。但是为什么要使用异常？


3. 不要担心辅助函数抛出的异常，但是你不能对所有异常进行单元测试，因为你不知道哪些异常可以由public函数抛出
4. 
   
5. 有一些工具（半）自动列出所有由助手抛出的异常等等。我查看了Doxygen的文档，但没有找到办法做到这一点。

1. recursively follow all functions theFunction() calls and look for exceptions thown by that function. This is a lot of work and you might forget to document an exception somewhere when you add an exception to a helper.
2. catch all exceptions thrown by helpers in theFunction() and convert them so you are sure only the exceptions you specify are thrown. But then why use exceptions?
3. do not worry about exceptions thrown by helper functions but then you can not unittest all exceptions because you do not know which exceptions can be thrown by the public function
4. have some tool which (semi)automatically lists all exceptions thrown by helpers etc. I looked in the documentation of Doxygen but did not find a way to do this.

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

I would like to use option 4 but I have not found a good solution yet, maybe it is doable with Doxygen? Or maybe I just want to document to much???

编辑：也许它不是很清楚，但我正在寻找一个简单的方法文档所有异常（最好使用Doxygen）一个函数可能会抛出，而不需要手动检查所有的帮助函数。一个简单的方法包括不记录所有异常或捕获和转换 theFunction（）'

edit: Maybe its not really clear but I am looking for an easy way to document all exceptions (preferably using Doxygen) a function might throw without manually checking all helper functions. An easy way includes 'do not document all exceptions' or 'catch and transform all exceptions in theFunction()'

推荐答案

我想出了以下手动解决方案。基本上我只是从我调用的成员复制 @throw 文档。如果Doxygen有一个类似于 @copydoc 的 @copythrows ，但以下操作将很有效：

I came up with the following manual solution. Basically I just copy the @throw documentation from members I call. It would be nice if Doxygen had a @copythrows similar to @copydoc, but the following will work:

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 code> * _ throws 到 EXCLUDE_SYMBOLS 。这可以确保这些组不会显示为模块。

Then in the Doxyfile configuration file add *_throws to EXCLUDE_SYMBOLS. This makes sure these groups do not show up as modules.

然后 B :: bar（）文档：

void B :: bar（）

执行其他操作。

void B::bar()
Do something else.

例外：

   FooExceptionought
例外：

   BarException

Exceptions:
  FooException
Exceptions:
  BarException

这篇关于如何记录一个函数可能抛出的所有异常？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！