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:
- See @Jeremy Sarao's answer, and tribal knowledge running around my head.
- Tribal knowledge. I have no idea how or where to find this info. in Doxygen documentation.
- 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.).
- Note that possible
param values are param[in], param[in,out], and param[out]. See these references for more details & official documentation:
- Is that an in or in/out parameter? Doxygen, C++
- Official Doxygen documentation for the
param special command: http://www.doxygen.nl/manual/commands.html#cmdparam
- Other code examples demonstrating Doxygen usage:
- STM32 how to get last reset status
- Error handling in C code
Other References:
- Documentation for GCC's super useful printf format attribute:
- https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html - see "format" section
- How to use formatting strings in user-defined functions?
- How should I properly use __attribute__ ((format (printf, x, y))) inside a class method in C++?
- 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
}
