记录重新引发错误的函数答案

【问题标题】：Documenting a function that re-throws an error记录重新引发错误的函数
【发布时间】：2020-03-27 00:57:26
【问题描述】：

我想知道在 doxygen 中正确的记录方式是什么。

拥有一个定义一些验证器的类，例如：

class Validators {
    /**
    * @fn A
    * @brief sees if x is too large.
    * @param[in] x the input to validate
    * @throws runtime_error when otx is too large.
    */
    static void A(int x) {
        if (x > 5) {
            throw std::runtime_error("x too large");
        }
    }
};

在如下函数中使用这个 valdator：

#include "validator.h"

class MyClass {
public:
    void setX(int x) {
        Validators::A(x);
    }
};

我应该如何记录setX() 重新抛出A() 抛出的runtime_error，还是根本不应该记录？

【问题讨论】：

也许使用\copydoc / \copybrief / \copydetails。请注意，\fn A 不是必需的，因为文档直接位于函数 A 的前面。

标签： c++ c++11 doxygen

【解决方案1】：

为了巧妙地做到这一点，我不得不稍微修改一下我的代码：

#include "validator.h"
class MyClass {
public:
    void setX(int x) {
        try {
            Validators::A(x);
        }
        catch (std::runtime_error & e) {
            throw e
        }
    }
};

这样做再次将@throws 添加到 Doxygen s 是有意义的，现在它显然被重新抛出了。

【讨论】：

只需使用throw; 而不是throw e; 以避免可能的切片。
不要只是接住再扔，你已经添加了 5 倍的行，根本没有说什么。
@Caleth 当可以抛出多个错误时，所有类型的 runtime_error （从它继承的自定义错误类）。你还觉得多余的线太多了吗？我在 Java 中被认为是为了确保其他人可以看到代码的作用。如果它提高了可读性，那么在这种情况下，一些额外的行不是问题。否则我将无法知道该函数会抛出 runtime_errors（将文档排除在外）。
@Jarod42 切片到底是什么意思？
你被教坏了。你知道它可以抛出，因为它不是 noexcept

【解决方案2】：

您应该记录它对调用者的意义。例如

class MyClass {
public:
    /**
    * @brief sets X
    * @param[in] x the new X
    * @throws runtime_error when x is invalid.
    */
    void setX(int x) {
        Validators::A(x);
    }
};

【讨论】：