Doxygen @return vs. @retval

[Sebastian Huber]

On 28/02/2019 17:06, Joel Sherrill wrote:
>
>
> On Thu, Feb 28, 2019 at 9:03 AM Sebastian Huber 
> <sebastian.huber at embedded-brains.de 
> <mailto:sebastian.huber at embedded-brains.de>> wrote:
>
>     Hello,
>
>     we agreed to use @retval instead of @return:
>
>     https://docs.rtems.org/branches/master/eng/coding-doxygen.html#doxygen-best-practices
>
>
> Is there going to be a global replacement or have they been purged?

This has to be done step by step. First we need clear guidance.

>     How should we indicate that not a particular value is returned, but
>     instead an element of a set. For example:
>
>     /**
>       * @brief Performs something and returns the operation status.
>       *
>       * @retval 0 Successful operation.
>       * @retval EIO Input/output error.
>       * @retval <otherwise> Any other value will not be returned.
>       */
>     int f(void);
>
>
> That last @retval doesn't match what I thought your statement above 
> indicated.
> The English on the last @retval say there are no more. Why even 
> include that?

To make it clear that nothing else is returned. Alternatively, we can 
globally state that functions only return the values documented, 
otherwise there is a documentation or code bug.

What about function pointer typedefs where you specify some requirements 
on a particular implementation, e.g.

/**
  * @brief Write to flash operation.
  *
  * @param[in, out] self The flash control.
  * @param[in] offset The offset to write from the flash begin in bytes.
  * @param[in] buffer The buffer containing the data to write.
  * @param[in] size_of_buffer The size of the buffer in bytes.
  *
  * @retval 0 Successful operation.
  * @retval -EIO An error occurred.  Please note that the value is negative.
  * @retval other All other values are reserved and must not be used.
  */
typedef int (*rtems_jffs2_flash_write)(
   rtems_jffs2_flash_control *self,
   uint32_t offset,
   const unsigned char *buffer,
   size_t size_of_buffer
);

>
> If you mean other errno's may be returned, that's different.
>
> What about the -1 and errno cases?

errno is a thread-local variable. You may document this in the @retval 
-1 text.

>
>
>     /**
>       * @brief Creates an object.
>       *
>       * @retval NULL Not enough resources to create an object.
>       * @retval <object> Pointer to created object.
>       */
>     T *create(void);
>
>     We may also use "[object]" or "{object}" or "object" or whatever.
>
>
> Can we use "instance of T"?

You cannot use spaces in "@retval value text" for the value.

>
> I assume you used object generically. Wouldn't it be the specific noun 
> for the created object?

My intent is to clarify which format we want to use for values which are 
no particular C constant, e.g "<value>", "[value]", "{value}", "value", 
or whatever.

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