Есть ли @retval-эквивалент для параметров out в Doxygen? (C / C ++) - PullRequest
Новая
       16

Есть ли @retval-эквивалент для параметров out в Doxygen? (C / C ++)

1 голос
/ 07 февраля 2020

Doxygen's @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);

Но что, если этот статус возвращается через выходной параметр? Есть ли соглашение для документирования этих значений? 

/**
 * 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);

В настоящее время мы будем говорить что-то вроде 

/**
 * ...
 * @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.
 */

, но было бы очень хорошо иметь что-то более структурированное.

Даже если это не встроенная команда, можно ли будет определить команду, такую ​​как @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.
 */

Я надеялся получить некоторое вдохновение от реализации @parblock, но похоже, что это встроенная команда со специальной внутренней поддержкой. Я не видел очевидного способа определения пользовательской команды, которая связывается с самой последней @param.

...