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

[Sebastian Huber]

On 28/02/2019 15:52, Sebastian Huber wrote:
> 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.
>

In ticket

http://devel.rtems.org/ticket/3721

Jens Schweikhardt proposed the following:

"1) only pointer parameters are annotated (since scalars are [in] by
  language definition)
2) [in] indicates that the pointer must point to an initialized object (it
  may be dereferenced by the directive)
3) [out] indicates that the object pointed to may be written by the
  directive
4) [inout] If both 2) and 3) apply."

I think these are good guidelines. What about annotation of const pointers? Should they get the [in] annotation which is somewhat redundant?

-- 
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.