Documenting a function that re-throws an error

Question

I wonder what the correct way of documenting, in doxygen, the following is.

Having a class defining some validators like:

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");
        }
    }
};

Using this valdator in a function like:

#include "validator.h"

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

How should I document that setX() re-throws the runtime_error thrown by A(), or should I not document that at all?

maybe use `\copydoc` / `\copybrief` / `\copydetails`. Note the `\fn A` is not necessary as the documentation is directly in front of the function A. — albert, Dec 02 '19 at 12:03

score 1 · Answer 1 · answered Dec 02 '19 at 15:30

1

You should document what it means to the caller. E.g.

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);
    }
};

answered Dec 02 '19 at 15:30

Caleth

52,200
2
44
75

I think this should be the accepted error. It helps someone trying to run/debug/edit/extend the code why errors are thrown at each level/function. The sentence you used before the code should be part of everyone's learning about error/exception throwing and handling. **"You should document what [the error] means _to the caller_."** That is a beautiful description. +1 – bballdave025 Aug 17 '23 at 18:30

score 0 · Answer 2 · answered Dec 02 '19 at 13:45

0

In order to do this neatly I had to change my code a bit:

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

Doing this it makes sense again to add @throws to Doxygen s now it is clearly re-thrown.

answered Dec 02 '19 at 13:45

SomeDutchGuy

2,249
4
16
42

2

just use `throw;` instead of `throw e;` to avoid possible slicing. – Jarod42 Dec 02 '19 at 13:57
don't just catch and re-throw, you've added 5x as many lines that say nothing at all. – Caleth Dec 02 '19 at 15:32
@Caleth When multiple error can be thrown all of type runtime_error (custom error classes inheriting from it). Do you still think the extra lines are too much? I was thought in Java to make sure others can see what code does. Some extra lines in that case are not an issue if it improves readability. I would not be able to know the function can throw runtime_errors otherwise (leaving the docs out). – SomeDutchGuy Dec 03 '19 at 06:54
1

@Jarod42 What exactly do you mean by slicing? – SomeDutchGuy Dec 03 '19 at 06:55
You were taught badly. You know it can throw because it is not noexcept – Caleth Dec 03 '19 at 08:17
@RuudVerhoef: [what-is-object-slicing](https://stackoverflow.com/questions/274626/what-is-object-slicing). Here you throw a `std::runtime_error`, even if you initially throw a derived exception (which is not the case in example). – Jarod42 Dec 03 '19 at 09:01
Make sure you put the semicolon after the line, `throw e`. It should read `throw e;`. I agree with @Jarod42; I think your code should end up reading simply `throw;`. – bballdave025 Aug 17 '23 at 18:32

Documenting a function that re-throws an error

2 Answers2