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

[Sebastian Huber]

On 13/03/2019 07:55, Sebastian Huber wrote:
> 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?
>

I updated the Doxygen guildelines:

What is currently not covered is the situation in which a function 
assigns or returns a non-const pointer. For example:

RTEMS_INLINE_ROUTINE Chain_Node *_Chain_Head(
   Chain_Control *the_chain
)
{
   return &the_chain->Head.Node;
}

typedef struct {
   [...]
   Chain_Node *position;
} Chain_Iterator;


RTEMS_INLINE_ROUTINE void _Chain_Iterator_registry_update(
   Chain_Iterator_registry *the_registry,
   Chain_Node              *the_node_to_extract
)
{
   Chain_Node *iter_node;
   Chain_Node *iter_tail;

   iter_node = _Chain_Head( &the_registry->Iterators );
   iter_tail = _Chain_Tail( &the_registry->Iterators );

   while ( ( iter_node = _Chain_Next( iter_node ) ) != iter_tail ) {
     Chain_Iterator *iter;

     iter = (Chain_Iterator *) iter_node;

     if ( iter->position == the_node_to_extract ) {
       if ( iter->direction == CHAIN_ITERATOR_FORWARD ) {
         iter->position = _Chain_Previous( the_node_to_extract );
       } else {
         iter->position = _Chain_Next( the_node_to_extract );
       }
     }
   }
}

The referenced object is not read or modified by the function itself. 
What should we do in terms of [out] and [in, out] specifiers here?

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