I started adopting the doxygen style of documenting my code and I'm bugged with a specific case of function parameter direction argument ([in], [out] or [in,out] for @param) .
If a pointer is passed to a function for read only, then this pointer is an [in] parameter.
If a pointer is passed to a function for read only, but this function makes a copy of the pointer to have access to it in module related functions for read only operations, this pointer is still [in].
If the function uses the pointer for read only, but the other module related functions use the pointer for write operations, what does that make the parameter direction in the function that takes it? An [in] parameter without const or an [in,out] parameter?
Example of what I mean in C++:
class SteeringWheel {
public: float rotation;
public: SteeringWheel(void) {
this->rotation = 0.f;
}
};
class Car {
private: SteeringWheel *steeringWheel;
public:
/**
* @param[in or in,out?] steeringWheel The steering wheel of the car.
*/
Car (SteeringWheel *steeringWheel) {
/* 1. Pointer is done read operations only in the scope of this function. */
this->steeringWheel = steeringWheel;
}
/**
* @param[in] degree Steering amount in degrees.
*/
void steer(float degree)
{
/* 2. Pointer is written to in a module related function called by the user. */
this->steeringWheel->rotation += degree;
}
};
int main(int argc, char **argv)
{
SteeringWheel steeringWheel();
/* car() uses steeringWheel as read only. */
Car car(&steeringWheel);
/* steer() uses steeringWheel from car() to write. */
car.steer(50.f);
return 0;
}
↧