Doxygen @return vs. @retval

[Gedare Bloom]

On Fri, Mar 1, 2019 at 4:57 AM Sebastian Huber <
sebastian.huber at embedded-brains.de> wrote:

> 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.
>
>
I prefer the global assumption that anything unspecified is not expected.

I would be OK with the convention of using "Otherwise" as a catch-all.


> 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.
>
>
@retval !NULL ...

It's a bit hideous, but correct.


>
> > 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.
>
> Ahhh... I would avoid <> which may cause confusion if < x  or >y  are used
to indicate range limits on return values.  [] and {} seem fine to me, if
we really need to define something. I might also consider #value#.


> --
> 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/20190302/d3033399/attachment-0001.html>