Using param[out] in Doxygen when setting a class property

Question

I am using Doxygen to document my c++ code. I have read this StackOverflow post about the difference between \return and \param[out]

Difference between param[out] and return in doxygen?

param[out] is used if you are setting something with a pointer in your function. If I have a method which sets a variable within its class is it still correct to use param[out] (the function is void)?

An example of what I mean - I have a method to convert polar coordinate inputs to Cartesian.

classConstructor(azimuth, elevation, roll)
{
     //set azimuth, elevation, roll
     convertToCartesian(azimuth, elevation, roll)
}

convertToCartesian(azimuth, elevation, roll)
{
     //someCode
     xPos = calcVector.X
     yPos = calcVector.Y
     zPos = calcVector.Z
}

xPos, yPos and xPos are private variables in my class, they are used later (accessed via getters);

No. param[out] is used for function parameters that get changed by the function. — Biffen
Is there a way this type of operation should be documented then? — MikeS159

MikeS159 MikeS159 · Accepted Answer · 2015-05-26T15:02:58

param[out] is used for pointers passed into a function. Anything external that is modified from within a function should be documented with comments.

Note: If you can't explain why you are editing variable inside a function which weren't passed in then you are probably writing bad code.

Using param[out] in Doxygen when setting a class property

1 Answers