What's the right way to reference a parameter in Doxygen?

Question

I have the following Doxygen documentation for a function:

/**
  @brief Does interesting things

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


        

Answer 1

Doxygen provides the command \p for indicating that the next word is a parameter to the function. You would use it like so:

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

I believe by default this will be represented using a typewriter font. I don't think this currently provides any auto-linking functionality, but potentially could in the future.

There is a related command, \a that is used to mark up member arguments. By default, it is displayed with emphasis in the text (<em>arg</em>)

You can find more information about the various Doxygen Special Commands reference.

Answer 2

I know you're asking about @parameters, but Google searches lead here for @return types too, so here's that answer:

Doxygen # usage in front of return value to create hyperlink to its definition:

Use the # symbol.

Full Example (see the @return types just below with a # in front of each of them):

#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.
/// @details    Feel free to add more details here,
///             perhaps
///             even
///             a
///             whole
///             paragraph.
/// @note       Optionally add a note too.
/// @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;
}

The Doxygen output now shows the error return types as a list of sub-bullets under the line Number of characters printed if OK, or < 0 if error:, and each of the error types is turned into a URL to their respective definitions due to the # character in front.

Doxygen References:

1. See @Jeremy Sarao's answer, and tribal knowledge running around my head.
2. Tribal knowledge. I have no idea how or where to find this info. in Doxygen documentation.
   • Maybe this is useful? http://www.doxygen.nl/manual/autolink.html
3. See a list of all of Doxygen's special commands here: http://www.doxygen.nl/manual/commands.html (ex: \brief or @brief, \note or @note, \details or @details, \example, etc.).
4. Note that possible param values are param[in], param[in,out], and param[out]. See these references for more details & official documentation:
   1. Is that an in or in/out parameter? Doxygen, C++
   2. Official Doxygen documentation for the param special command: http://www.doxygen.nl/manual/commands.html#cmdparam
5. Other code examples demonstrating Doxygen usage:
   1. STM32 how to get last reset status
   2. Error handling in C code

Other References:

1. Documentation for GCC's super useful printf format attribute:
   1. https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html - see "format" section
   2. How to use formatting strings in user-defined functions?
   3. How should I properly use __attribute__ ((format (printf, x, y))) inside a class method in C++?
2. Basic printf wrapper implementation: https://github.com/adafruit/ArduinoCore-samd/blob/master/cores/arduino/Print.cpp#L189

Other Doxygen Examples:

(Copied from my eRCaGuy_dotfiles project here)

Full Doxygen function header example:

/// \brief          A brief one or two line description of the function.
/// \note           An important note the user should be aware of--perhaps many lines.
/// \details        Extra details.
///                 Perhaps
///                 even
///                 a long
///                 paragraph.
/// \param[in]      var1            Description of variable one, an input
/// \param[in]      var2            Description of variable two, an input
/// \param[out]     var3            Description of variable three, an output (usu. via a pointer
///                                 to a variable)
/// \param[in,out]  var4            Description of variable four, an input/output (usu. via a
///                                 pointer) since its initial value is read and used, but then 
///                                 it is also updated by the function at some point
/// \return         Description of return types. It may be an enum, with these
///                 possible values:
///                 - #ENUM_VALUE_1
///                 - #ENUM_VALUE_2
///                 - #ENUM_VALUE_3
my_enum_t myFunc(int var1, int var2, int* var3, int* var4)
{
    // function implementation here

    my_enum_t error = ENUM_VALUE_1;

    // Check for NULL pointers
    if (!var3 || !var4)
    {
        // var3 or var4 are NULL pointers, which means they can't be dereferenced
        error = ENUM_VALUE_2;
        goto done;
    }

    if (something_else)
    {
        error = ENUM_VALUE_3;
        goto done;
    }

done:
    return error;
}

You may also use @ instead of \:

/// @brief          A brief one or two line description of the function.
/// @param[in]      var1            Description of variable one, an input
/// @param[in]      var2            Description of variable two, an input
/// @param[out]     var3            Description of variable three, an output (usu. via a pointer
///                                 to a variable)
/// @param[in,out]  var4            Description of variable four, an input/output (usu. via a
///                                 pointer) since its initial value is read and used, but then 
///                                 it is also updated by the function at some point
/// @return         None
void myFunc(int var1, int var2, int* var3, int* var4)
{
    // function implementation here
}

And here's this shorter version again now with \ again instead of @:

/// \brief          A brief one or two line description of the function.
/// \param[in]      var1            Description of variable one, an input
/// \param[in]      var2            Description of variable two, an input
/// \param[out]     var3            Description of variable three, an output (usu. via a pointer
///                                 to a variable)
/// \param[in,out]  var4            Description of variable four, an input/output (usu. via a
///                                 pointer) since its initial value is read and used, but then 
///                                 it is also updated by the function at some point
/// \return         None
void myFunc(int var1, int var2, int* var3, int* var4)
{
    // function implementation here
}

Answer 3

use the "#" symbol in front of the parameter you want to reference:

#pfirst must have been previously passed through BarrelFiller()

(in the doxygen manual)