[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             |   Keywords:
Blocked By:                     |   Blocking:
--------------------------------+--------------------
 It would seem that a number of doxygen comments in the source code do not
 match the function's behavior.

 Example: /cpukit/include/rtems/rtems/message.h
 {{{
 171     /**
 172      * @brief RTEMS Message Queue Receive
 173      *
 174      * This routine implements the rtems_message_queue_receive
 directive.
 175      * This directive is invoked when the calling task wishes to
 receive
 176      * a message from the message queue indicated by ID. The received
 177      * message is to be placed in buffer. If no messages are
 outstanding
 178      * and the option_set indicates that the task is willing to block,
 179      * then the task will be blocked until a message arrives or until,
 180      * optionally, timeout clock ticks have passed.
 181      *
 182      * @param[in] id is the queue id
 183      * @param[in] buffer is the pointer to message buffer
 184      * @param[in] size is the size of message receive
 185      * @param[in] option_set is the options on receive
 186      * @param[in] timeout is the number of ticks to wait
 187      *
 188      * @retval This method returns RTEMS_SUCCESSFUL if there was not
 an
 189      *         error. Otherwise, a status code is returned indicating
 the
 190      *         source of the error.
 191      */
 192     rtems_status_code rtems_message_queue_receive(
 193       rtems_id        id,
 194       void           *buffer,
 195       size_t         *size,
 196       rtems_option    option_set,
 197       rtems_interval  timeout
 198     );
 }}}

 Since the parameters "buffer" and "size" are output parameters, the
 comment should say
 {{{
 183      * @param[out] buffer is the pointer to message buffer
 184      * @param[out] size is the size of message receive
 }}}

 There are other functions where this is inconsistent, so a look at all
 functions taking pointer parameters is likely a good idea.

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