我知道你问的是@param
eters,但谷歌搜索也在这里引导@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.
/// @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;
}
Doxygen 输出现在将错误返回类型显示为行下的子项目符号列表Number of characters printed if OK, or < 0 if error:
,并且由于前面的字符,每个错误类型都转换为它们各自定义的 URL#
。
Doxygen 参考资料:
- 请参阅@Jeremy Sarao 的回答,以及在我脑海中萦绕的部落知识。
- 部落知识。我不知道如何或在哪里可以找到此信息。在 Doxygen 文档中。
- 在此处查看 Doxygen 的所有特殊命令的列表:http: //www.doxygen.nl/manual/commands.html(例如:
\brief
或@brief
、\note
或@note
、\details
或@details
、\example
等)。
- 请注意,可能的
param
值为param[in]
、param[in,out]
和param[out]
。有关更多详细信息和官方文档,请参阅这些参考资料:
- 这是一个输入或输入/输出参数吗?氧,C++
param
特殊命令的官方 Doxygen 文档:http: //www.doxygen.nl/manual/commands.html#cmdparam
- 其他演示 Doxygen 用法的代码示例:
- STM32如何获得最后的复位状态
- C 代码中的错误处理
其他参考:
- GCC 超级有用的 printf 格式属性的文档:
- https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html - 见“格式”部分
- 如何在用户定义的函数中使用格式化字符串?
- 我应该如何在 C++ 的类方法中正确使用 __attribute__ ((format (printf, x, y)))?
- 基本
printf
包装器实现:https ://github.com/adafruit/ArduinoCore-samd/blob/master/cores/arduino/Print.cpp#L189
其他 Doxygen 示例:
(从我的 eRCaGuy_dotfiles 项目复制而来)
完整的 Doxygen 函数头示例:
/// \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;
}
您也可以使用@
代替\
:
/// @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
}
这是这个较短的版本,现在\
再次使用而不是@
:
/// \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
}