Doxygen@retval
提供了一种清晰的方法来记录多个返回值:
/**
* 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);
Run Code Online (Sandbox Code Playgroud)
但是如果通过输出参数返回该状态怎么办?是否有记录这些值的约定?
/**
* 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);
Run Code Online (Sandbox Code Playgroud)
目前我们会说类似的话
/**
* ...
* @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.
*/
Run Code Online (Sandbox Code Playgroud)
但如果有更结构化的东西那就太好了。
即使它不是内置命令,是否可以定义一个类似@paramval
绑定到最新命令的命令@param
?例如,
/**
* ...
* @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.
*/
Run Code Online (Sandbox Code Playgroud)
我希望从 的实现中获得一些灵感@parblock
,但看起来它是一个具有特殊内部支持的内置命令。我没有看到一种明显的方法来定义绑定到最新的@param
.