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, Aug 08 '14 at 10:41
Is there a way this type of operation should be documented then? — MikeS159, Aug 08 '14 at 10:54

score 0 · Accepted Answer · answered May 26 '15 at 15:02

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 Answers1