[RTEMS Project] #3721: Doxygen param "in/out" attributes not matching function behavior

[RTEMS trac]

#3721: Doxygen param "in/out" attributes not matching function behavior
-------------------------------+---------------------
 Reporter:  Jens Schweikhardt  |       Owner:  (none)
     Type:  enhancement        |      Status:  new
 Priority:  normal             |   Milestone:
Component:  doc                |     Version:  5
 Severity:  normal             |  Resolution:
 Keywords:                     |  Blocked By:
 Blocking:                     |
-------------------------------+---------------------

Comment (by Joel Sherrill):

 Replying to [comment:2 Jens Schweikhardt]:
 > OK, from the description it was not clear that size is actually [inout].
 Maybe there's room for improvement as well.

 I think this may be the only case in the Classic API where the value of a
 *argument is expected to have a value set by the caller.. So I was picking
 a bit at the unlucky choice for an example. :)

 The fact you landed on this one as an example without realizing that may
 indicate the documentation could be improved. :(

 This still doesn't answer the question of how an output parameter via
 pointer should be annotated. The pointer has a value on input (e.g. in)
 but the *pointer is where the output goes.

 And the Doxygen for this method doesn't indicate that the buffer and *size
 will be set on success. :(


 > As for "Others may indicate" I would argue that in that case "in" is
 redundant, or even pointless, since in C parameters are always passed by
 value, so can only be "in" by language definition.

 Yes. This is true. But the personality of the people who did this are anal
 about consistency. If you say out or inout for some, what is the output
 for those where nothing is said in the input? Does it look like a mistake
 not to include in annotation? It is redundant but makes things consistent.

 > Nit-pick: the coremsgseize.c you reference says "@brief Size" where it
 meant "Seize". :-)

 Got it. I fixed that locally and will push a commit when I catch my next
 round of patches.

 Interestingly, Seize breaks the rule of "i before e except after c"

--
Ticket URL: <http://devel.rtems.org/ticket/3721#comment:3>
RTEMS Project <http://www.rtems.org/>
RTEMS Project