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

I have the following Doxygen documentation for a function:

/**
  @brief Does interesting things

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

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

Note that pfirst is a parameter, and that it is referenced in the preconditions.

I've surrounded it with quotation marks here because I want to stand it off from the rest of the text. But it would be nice to do this in such a way that Doxygen will highlight the command and, preferably, link it to the parameter definition. Is there a way to do this?

It would be especially nice if this would happen using only the default configuration (or minor alterations thereof).

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.

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
}