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