On Fri, Mar 1, 2019 at 4:57 AM Sebastian Huber < sebastian.hu...@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.hu...@embedded-brains.de > > <mailto:sebastian.hu...@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.hu...@embedded-brains.de > PGP : Public key available on request. > > Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG. > > _______________________________________________ > devel mailing list > devel@rtems.org > http://lists.rtems.org/mailman/listinfo/devel
_______________________________________________ devel mailing list devel@rtems.org http://lists.rtems.org/mailman/listinfo/devel
