72

我有一个函数的以下 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 突出显示命令的方式执行此操作,并且最好将其链接到参数定义。有没有办法做到这一点?

如果仅使用默认配置(或对其进行细微更改)会发生这种情况,那就太好了。

4

3 回答 3

82

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

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

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

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

您可以找到有关各种 Doxygen特殊命令参考的更多信息。

于 2013-03-16T22:16:55.510 回答
8

我知道你问的是@parameters,但谷歌搜索也在这里引导@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 参考资料:

  1. 请参阅@Jeremy Sarao 的回答,以及在我脑海中萦绕的部落知识。
  2. 部落知识。我不知道如何或在哪里可以找到此信息。在 Doxygen 文档中。
  3. 在此处查看 Doxygen 的所有特殊命令的列表:http: //www.doxygen.nl/manual/commands.html(例如:\brief@brief\note@note\details@details\example等)。
  4. 请注意,可能的param值为param[in]param[in,out]param[out]。有关更多详细信息和官方文档,请参阅这些参考资料:
    1. 这是一个输入或输入/输出参数吗?氧,C++
    2. param特殊命令的官方 Doxygen 文档:http: //www.doxygen.nl/manual/commands.html#cmdparam
  5. 其他演示 Doxygen 用法的代码示例:
    1. STM32如何获得最后的复位状态
    2. C 代码中的错误处理

其他参考:

  1. GCC 超级有用的 printf 格式属性的文档:
    1. https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html - 见“格式”部分
    2. 如何在用户定义的函数中使用格式化字符串?
    3. 我应该如何在 C++ 的类方法中正确使用 __attribute__ ((format (printf, x, y)))?
  2. 基本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
}
于 2019-06-24T23:58:20.440 回答
0

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

#pfirst must have been previously passed through BarrelFiller()

在 doxygen 手册中

于 2017-05-05T20:48:43.460 回答