<div dir="ltr"><div dir="ltr"><br></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Fri, Mar 1, 2019 at 4:57 AM Sebastian Huber <<a href="mailto:sebastian.huber@embedded-brains.de">sebastian.huber@embedded-brains.de</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">On 28/02/2019 17:06, Joel Sherrill wrote:<br>
><br>
><br>
> On Thu, Feb 28, 2019 at 9:03 AM Sebastian Huber <br>
> <<a href="mailto:sebastian.huber@embedded-brains.de" target="_blank">sebastian.huber@embedded-brains.de</a> <br>
> <mailto:<a href="mailto:sebastian.huber@embedded-brains.de" target="_blank">sebastian.huber@embedded-brains.de</a>>> wrote:<br>
><br>
>     Hello,<br>
><br>
>     we agreed to use @retval instead of @return:<br>
><br>
>     <a href="https://docs.rtems.org/branches/master/eng/coding-doxygen.html#doxygen-best-practices" rel="noreferrer" target="_blank">https://docs.rtems.org/branches/master/eng/coding-doxygen.html#doxygen-best-practices</a><br>
><br>
><br>
> Is there going to be a global replacement or have they been purged?<br>
<br>
This has to be done step by step. First we need clear guidance.<br>
<br>
>     How should we indicate that not a particular value is returned, but<br>
>     instead an element of a set. For example:<br>
><br>
>     /**<br>
>       * @brief Performs something and returns the operation status.<br>
>       *<br>
>       * @retval 0 Successful operation.<br>
>       * @retval EIO Input/output error.<br>
>       * @retval <otherwise> Any other value will not be returned.<br>
>       */<br>
>     int f(void);<br>
><br>
><br>
> That last @retval doesn't match what I thought your statement above <br>
> indicated.<br>
> The English on the last @retval say there are no more. Why even <br>
> include that?<br>
<br>
To make it clear that nothing else is returned. Alternatively, we can <br>
globally state that functions only return the values documented, <br>
otherwise there is a documentation or code bug.<br>
<br></blockquote><div><br></div><div>I prefer the global assumption that anything unspecified is not expected.</div><div><br class="gmail-Apple-interchange-newline">I would be OK with the convention of using "Otherwise" as a catch-all. <br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
What about function pointer typedefs where you specify some requirements <br>
on a particular implementation, e.g.<br>
<br>
/**<br>
  * @brief Write to flash operation.<br>
  *<br>
  * @param[in, out] self The flash control.<br>
  * @param[in] offset The offset to write from the flash begin in bytes.<br>
  * @param[in] buffer The buffer containing the data to write.<br>
  * @param[in] size_of_buffer The size of the buffer in bytes.<br>
  *<br>
  * @retval 0 Successful operation.<br>
  * @retval -EIO An error occurred.  Please note that the value is negative.<br>
  * @retval other All other values are reserved and must not be used.<br>
  */<br>
typedef int (*rtems_jffs2_flash_write)(<br>
   rtems_jffs2_flash_control *self,<br>
   uint32_t offset,<br>
   const unsigned char *buffer,<br>
   size_t size_of_buffer<br>
);<br>
<br>
><br>
> If you mean other errno's may be returned, that's different.<br>
><br>
> What about the -1 and errno cases?<br>
<br>
errno is a thread-local variable. You may document this in the @retval <br>
-1 text.<br>
<br>
><br>
><br>
>     /**<br>
>       * @brief Creates an object.<br>
>       *<br>
>       * @retval NULL Not enough resources to create an object.<br>
>       * @retval <object> Pointer to created object.<br>
>       */<br>
>     T *create(void);<br>
><br>
>     We may also use "[object]" or "{object}" or "object" or whatever.<br>
><br>
><br>
> Can we use "instance of T"?<br>
<br>
You cannot use spaces in "@retval value text" for the value.<br>
<br></blockquote><div><br></div><div>@retval !NULL ...</div><div><br></div><div>It's a bit hideous, but correct.</div><div><br></div><div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
><br>
> I assume you used object generically. Wouldn't it be the specific noun <br>
> for the created object?<br>
<br>
My intent is to clarify which format we want to use for values which are <br>
no particular C constant, e.g "<value>", "[value]", "{value}", "value", <br>
or whatever.<br>
<br></blockquote><div>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#.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
-- <br>
Sebastian Huber, embedded brains GmbH<br>
<br>
Address : Dornierstr. 4, D-82178 Puchheim, Germany<br>
Phone   : +49 89 189 47 41-16<br>
Fax     : +49 89 189 47 41-09<br>
E-Mail  : <a href="mailto:sebastian.huber@embedded-brains.de" target="_blank">sebastian.huber@embedded-brains.de</a><br>
PGP     : Public key available on request.<br>
<br>
Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG.<br>
<br>
_______________________________________________<br>
devel mailing list<br>
<a href="mailto:devel@rtems.org" target="_blank">devel@rtems.org</a><br>
<a href="http://lists.rtems.org/mailman/listinfo/devel" rel="noreferrer" target="_blank">http://lists.rtems.org/mailman/listinfo/devel</a></blockquote></div></div>