[hipl-dev] Direction of a function parameter
- From: Samu Varjonen <samu.varjonen@xxxxxxx>
- To: hipl-dev@xxxxxxxxxxxxx
- Date: Wed, 05 Jan 2011 12:29:01 +0200
Hi,I was editing the HIPL code on my branch and noticed that even though there are the doxygen headers for the functions, it is sometimes painful to get the idea what the function is doing. Especially which parameters are used for output.
Doxygen has a way to solve this by telling it explicitly. /*! Copies bytes from a source memory area to a destination memory area, where both areas may not overlap. @param[out] dest The memory area to copy to. @param[in] src The memory area to copy from. @param[in] n The number of bytes to copy */ void memcpy(void *dest, const void *src, size_t n);One, could also argue that there should be a const before all of the input parameters and that they could be used to indicate the same. But I think there are still parts of the code left that do not use const.
I was discussing this with Miika and we came to the conclusion that its inconvenient to mark the direction to all of the doxygen function headers but it would make more sense to write sensible documentation that explicitly state these things.
What is the general feeling about this? Go for the const correct code and fix the comments when you find a vague one and forget about the direction argument of doxygen?
Other related posts:
- » [hipl-dev] Direction of a function parameter - Samu Varjonen
- » [hipl-dev] Re: Direction of a function parameter - Stefan Götz
- » [hipl-dev] Re: Direction of a function parameter - Diego Biurrun
- » [hipl-dev] Re: Direction of a function parameter - Tobias Heer
- » [hipl-dev] Re: Direction of a function parameter - René Hummen