Is there a @retval equivalent for out parameters? (C/C++)

[dbort]

Doxygen's @retval provides a clear way to document multiple return values:

/**
 * Do the thing to the other thing.
 *
 * @param[in] other_thing The thing to do it to.
 *
 * @retval STATUS_OK on success.
 * @retval STATUS_BAD_ARGS if the other thing wasn't right.
 * @retval STATUS_TIMED_OUT if the thing timed out.
 */
status_t do_the_thing(thing_t other_thing);

But what if that status is returned via an output parameter? Is there a convention for documenting those values?

/**
 * Do a couple things to the other thing.
 *
 * @param[in] other_thing The thing to do it to.
 * @param[out] out_status_1 The status of the first thing done.
 * @param[out] out_status_2 The status of the second thing done.
 */
void do_a_couple_things(
    thing_t other_thing, status_t *out_status_1, status_t *out_status_2);

Currently we'll say something like

/**
 * ...
 * @param[out] out_status_1 The status of the first thing done.
 *     - STATUS_OK on success.
 *     - STATUS_BAD_ARGS if the other thing wasn't right.
 *     - STATUS_TIMED_OUT if the first thing timed out.
 * @param[out] out_status_2 The status of the second thing done.
 *     - STATUS_OK on success.
 *     - STATUS_NOT_FOUND if the thing wasn't in the second thing index.
 *     - STATUS_NO_MEMORY if there wasn't enough space for the thing.
 */

but it'd be really nice to have something more structured.

Even if it's not a builtin command, would it be possible to define a command like @paramval that binds to the most-recent @param? E.g.,

~~~
/*
* ...
* @param[out] out_status_1 The status of the first thing done.
* @paramval STATUS_OK on success.
* @paramval STATUS_BAD_ARGS if the other thing wasn't right.
* @paramval STATUS_TIMED_OUT if the first thing timed out.
* @param[out] out_status_2 The status of the second thing done.
* @paramval STATUS_OK on success.
* @paramval STATUS_NOT_FOUND if the thing wasn't in the second thing index.
* @paramval STATUS_NO_MEMORY if there wasn't enough space for the thing.
/
~~~

I was hoping to get some inspiration from the implementation of @parblock, but it looks like it's a built-in command with special internal support. I didn't see an obvious way to define a custom command that binds to the most-recent @param.

[dbort]

We're just going to stick with bulleted lists.