Question

Please consider the following example:

class Example
{
    int &_m;

public:
    /**
     * An example constructor.
     *
     * @param myint Reference to some int.
     */
    Example(int& myint)
        : _m(myint)
    {
    }

    void change()
    {
        _m = 5;
    }
};

Should I mark the myint parameter @param[out]? The constructor itself doesn’t use it as an output argument, it is however stored in the class and can be modified by the change() method.

Does the following rule of thumb make sense: @param[in] for const pointers and references, @param[in,out] for non-const ones?

Answer 1

The documentation is for you and readers of your class, so it should provide the information that will make it most clear what’s going on. The object seems to be designed to write to the reference. So marking it as an out parameter is not unreasonable. If it accurately communicates the intended use of the reference parameter, then you should use it as such.