我有以下用于函数的 Doxygen 文档：
/**
@brief Does interesting things
@param[in] pfirst The first parameter: a barrel full of monkeys
@pre
"pfirst" must have been previously passed through BarrelFiller()
*/
注意pfirst是一个参数，它在前置条件中被引用。
我在这里用引号将它括起来，因为我想将它与文本的其余部分分开。但是最好以 Doxygen 突出显示命令的方式执行此操作，并且最好将其链接到参数定义。有没有办法做到这一点？
如果仅使用默认配置（或对其进行细微更改）会发生这种情况，那就太好了。
【问题讨论】：
标签： doxygen
Doxygen 提供命令\p 用于指示下一个单词是函数的参数。你可以这样使用它：
... the \p x and \p y coordinates are used to ...
我相信默认情况下这将使用打字机字体表示。我认为这目前不提供任何自动链接功能，但将来可能会提供。
有一个相关的命令，\a，用于标记成员参数。默认在文本中强调显示（<em>arg</em>）
您可以找到有关各种 Doxygen 的更多信息Special Commands reference。
【讨论】：
paramname 的成员class)，不仅以类似方式呈现作为默认样式表中的参数。如果您要剥 Doxygen 的输出，这显然很重要，但目前还没有经济实惠的方法。
\ 替换为 @ 并获得相同的结果。所以，@p 也可以在这里工作。
我知道您问的是 @parameters，但 Google 搜索也会在此处搜索 @return 类型，所以答案如下：
# 在返回值前面使用创建超链接到它的定义：使用# 符号。
完整示例（请参阅下面的 @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前面的字符。
\brief 或 @brief、\note 或 @note、\details 或 @details、\example等）。param 值为 param[in]、param[in,out] 和 param[out]。有关更多详细信息和官方文档，请参阅这些参考资料：
param 特殊命令的官方 Doxygen 文档：http://www.doxygen.nl/manual/commands.html#cmdparam
printf 包装器实现：https://github.com/adafruit/ArduinoCore-samd/blob/master/cores/arduino/Print.cpp#L189
（复制自my eRCaGuy_dotfiles project here）
完整的 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
}
【讨论】：
在要引用的参数前使用“#”符号：
#pfirst must have been previously passed through BarrelFiller()
【讨论】：
# 用于引用成员变量，而不是函数参数。
pfirst 是一个参数，则会产生“警告：无法解析对pfirst 的显式链接请求”，并且散列按字面意思写入生成的文档中。如果pfirst 是成员函数或变量，则输出是一个花哨的链接。
# 符号在@return 类型（值）前面工作，以创建指向每个返回值定义的链接，这是我真正想知道的。例如：/// @return Number of characters printed, or < 0 if error: #OVERFLOW or #UART。现在，在我生成的 Doxygen 中，“OVERFLOW”和“UART”显示为它们各自定义的超链接，这很棒。