Doxygen @return vs. @retval

[Joel Sherrill]

On Thu, Feb 28, 2019 at 9:03 AM Sebastian Huber <
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?


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

If you mean other errno's may be returned, that's different.

What about the -1 and errno cases?


> /**
>   * @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"?

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

>
> --
> 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.
>
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rtems.org/pipermail/devel/attachments/20190228/00dd8242/attachment-0002.html>