Doxygen @param and [in], [out] or [in,out]?

[Sebastian Huber]

Hello,

we agreed to use @param for function parameter documentation:

https://docs.rtems.org/branches/master/eng/coding-doxygen.html#doxygen-best-practices

Do we want to use [in], [out] or [in,out] as well?

If yes, how are [in], [out] or [in,out] used exactly? For example 
consider values passed by reference. Is in

void f(int *a)
{
   if (*a == 0) {
     *a = 1;
   }
}

the parameter a an [in,out] parameter? What about

void g(int *a)
{
   *a = 1;
}

?

How can we ensure that this extra information is consistent throughout 
the documentation?

I think we should remove all the [in], [out] or [in,out] stuff. From the 
parameter type it is quite obvious how they are used, e.g. "type *param" 
vs. "const type *param". For passed by value it is clear that they are 
input parameters. Output only use is normally indicated by the function 
name, e.g. "initialize", "set", "create", etc.

-- 
Sebastian Huber, embedded brains GmbH

Address : Dornierstr. 4, D-82178 Puchheim, Germany
Phone   : +49 89 189 47 41-16
Fax     : +49 89 189 47 41-09
E-Mail  : sebastian.huber at embedded-brains.de
PGP     : Public key available on request.

Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG.