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 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).

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 }