Каков правильный способ ссылки на параметр в Doxygen?

У меня есть следующая документация Doxygen для функции:

/**
  @brief Does interesting things

  @param[in]  pfirst The first parameter: a barrel full of monkeys

  @pre
    "pfirst" must have been previously passed through BarrelFiller()
*/

Обратите внимание, что pfirst является параметром и что он ссылается в предварительных условиях.

Я окружил его кавычками здесь, потому что я хочу выдержать это от остальной части текста. Но было бы неплохо сделать это таким образом, чтобы Doxygen выделил команду и, предпочтительно, привязал ее к определению параметра. Есть ли способ сделать это?

Было бы особенно приятно, если бы это произошло, используя только конфигурацию по умолчанию (или незначительные изменения).

Ответы

Ответ 1

Doxygen предоставляет команду \p для указания того, что следующее слово является параметром функции. Вы бы использовали это так:

... the \p x and \p y coordinates are used to ...

Я считаю, что по умолчанию это будет представлено с использованием шрифта пишущей машинки. Я не думаю, что в настоящее время это обеспечивает какую-либо функцию автоматической связи, но потенциально может в будущем.

Существует связанная команда \a которая используется для разметки аргументов членов. По умолчанию он отображается с акцентом в тексте (<em>arg</em>)

Вы можете найти больше информации о различных специальных командах Doxygen.

Ответ 2

используйте символ "#" перед параметром, на который вы хотите сослаться:

#pfirst must have been previously passed through BarrelFiller()

(в руководстве по Doxygen)

Ответ 3

Я знаю, что вы спрашиваете о @param, но поиски Google приводят здесь и типы @return, так что вот ответ:

Использование Doxygen # перед возвращаемым значением для создания гиперссылки на его определение:

Используйте символ #.

Полный пример (см. Типы @return чуть ниже с # перед каждым из них):

#include <stdarg.h> // for va_list, va_start, va_end
#include <stdio.h>  // for vsnprintf

// Function prototype:

int debug_printf(const char *format, ...) __attribute__((format(printf, 1, 2)));

// Function definition:

/// @brief      Function to print out data through serial UART for debugging
/// @param[in]  format  'printf'-like format string
/// @param[in]  ...     'printf'-like variadic list of arguments corresponding to the format string
/// @return     Number of characters printed if OK, or < 0 if error:
///             - #DEBUG_ERR_ENCODING
///             - #DEBUG_ERR_OVERFLOW
///             - #DEBUG_ERR_UART
int debug_printf(const char *format, ...)
{
    int num_chars_printed;

    va_list args;
    va_start(args, format);

    // Use 'vsnprintf()' now here to format everything into a single string buffer, then send 
    // out over the UART
    // - num_chars_printed could be set to one of the error codes listed above here

    va_end(args);

    return num_chars_printed;
}

Выходные данные Doxygen теперь показывают типы возвращаемых ошибок в виде списка подпунктов под строкой Number of characters printed if OK, or < 0 if error: и каждый из типов ошибок превращается в URL-адрес соответствующих определений из-за символ # впереди.

Ссылки на кислород:

  1. См. Ответ Джереми Сарао, и знания о племени бегают вокруг моей головы.
  2. Племенные знания. Я понятия не имею, как и где найти эту информацию. в документации по Doxygen.

Другие ссылки

  1. Документация по GCC супер полезный атрибут формата printf:
    1. https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html - см. раздел "Формат"
    2. Как использовать строки форматирования в пользовательских функциях?
    3. Как правильно использовать __attribute__ ((format (printf, x, y))) внутри метода класса в C++?
  2. Базовая реализация оболочки printf: https://github.com/adafruit/ArduinoCore-samd/blob/master/cores/arduino/Print.cpp#L189