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

[Sebastian Huber]

On 05/04/2019 09:44, Sebastian Huber wrote:
> 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?
>

Another special case are handler arguments, e.g.

rtems_status_code rtems_interrupt_handler_install(
   rtems_vector_number vector,
   const char *info,
   rtems_option options,
   rtems_interrupt_handler handler,
   void *arg
);

The arg is only stored in rtems_interrupt_handler_install() and later 
passed to the handler call.

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