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.hu...@embedded-brains.de
PGP : Public key available on request.
Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG.
_______________________________________________
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel
