在 Doxygen 引用参数的正确方法是什么？

小开

最佳答案

Doxy提供了命令 \p，用于指示下一个单词是函数的参数。你会这样使用它:

... the \p x and \p y coordinates are used to ...

我相信默认情况下，这将表示使用打字机字体。我不认为这目前提供任何自动链接功能，但可能在未来。

有一个相关的命令 \a用于标记成员参数。默认情况下，它在文本(<em>arg</em>)中以强调显示

您可以找到关于各种 Doxy参考特别命令的更多信息。

小开

在要引用的参数前使用“ #”符号:

#pfirst must have been previously passed through BarrelFiller()

(在氧气手册里)

小开

我知道你在问关于 @parameters 的问题，但是谷歌搜索引擎在这里也搜索 @return类型，所以这里有一个答案:

在返回值前使用 Doxy`#`来创建到其定义的超链接:

使用 #符号。

全例(请看下面的 ABC0类型，每个类型前面都有一个 #) :

#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;
}

Doxy输出现在将错误返回类型显示为 Number of characters printed if OK, or < 0 if error:，由于前面的 #字符，每个错误类型都转换为指向其各自定义的 URL行下的子项目列表。

参考文献:

看看 @ Jeremy Sarao 的回答和部落知识在我脑海里盘旋。
部落知识。我不知道如何或在哪里可以找到这些信息。在 Doxygen 的文件。
- 也许这个有用
在这里可以看到一个列表，其中列出了 Doxy的所有特殊命令: http://www.doxygen.nl/manual/commands.html(例如: \brief或 @brief、 \note或 @note、 \details或 @details、 \example等)。
请注意，可能的 param值是 param[in]、 param[in,out]和 param[out]。有关更多细节和官方文档，请参阅以下参考资料:
1. - 这是一个输入/输出参数吗?-氧气，C + +
2. param特别指挥部的正式 Doxy文档: http://www.doxygen.nl/manual/commands.html#cmdparam
演示 Doxy用法的其他代码示例:
1. STM32如何获得最后的重置状态
2. C 代码中的错误处理

其他参考资料:

GCC 超级有用的 printf 格式属性文档:
基本 printf包装器实现: https://github.com/adafruit/ArduinoCore-samd/blob/master/cores/arduino/Print.cpp#L189

其他吸氧的例子:

(从我的 eRCaGuy _ dotfiles 项目复制)

完整 Doxy函数头示例:

/// \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
}

在 Doxygen 引用参数的正确方法是什么？

在返回值前使用 Doxy#来创建到其定义的超链接:

参考文献:

其他参考资料:

其他吸氧的例子:

在返回值前使用 Doxy`#`来创建到其定义的超链接: