doxygen开始使用doxygen


备注

本节概述了doxygen是什么,以及开发人员可能想要使用它的原因。

它还应该提到doxygen中的任何大型主题,并链接到相关主题。由于doxygen的文档是新的,您可能需要创建这些相关主题的初始版本。

评论您的代码

有几种方法可以将注释块标记为详细描述,以便Doxygen解析此注释块并将其作为以下代码项的描述添加到文档中。第一个也是最常见的是C样式注释,在注释开始序列中带有额外的星号,例如:

/**
 * … text …
 */
int dummy_var;
 

下一个选择是使用Qt样式并在C样式注释块的打开序列之后添加感叹号(!):

/*!
 * … text …
 */
void foo(void);
 

第三种方法是使用至少两个C ++注释行的块,其中每一行以一个额外的斜杠或感叹号开头:

/// 
/// ... text ... 
///
 

要么

//! 
//! ... text ... 
//!
 

有些人喜欢在文档中更明显地显示他们的评论块。为此,您可以使用以下内容:

 /********************************************//** 
  * ... text 
  ***********************************************/
 

注意2斜杠结束正常注释块并启动一个特殊注释块。

/////////////////////////////////////////////////
/// ... text ...
/////////////////////////////////////////////////
 

为了构建和生成生成的文档,Doxygen提供了大量(> 170)特殊命令。文档中的所有命令都以反斜杠()或at符号(@)开头。

例如

/**
 * \brief    A brief description in one short sentence.
 */
 

相当于

/**
 * @brief    A brief description in one short sentence.
 */
 

简要说明还有几种可能性:

可以将\brief 命令与上述注释块之一一起使用。此命令在段落的末尾结束,因此详细描述在空行之后。

/** \brief Brief description. 
 * Brief description continued. 
 * 
 * Detailed description starts here. 
 */ 
 

如果配置文件中的JAVADOC_AUTOBRIEF 设置为YES ,那么使用JavaDoc样式的注释块将自动开始一个简短的描述,该描述以第一个点结尾,后跟空格或新行。

/// Brief description which ends at this dot. Details follow 
/// here. 
 

最后这里有一个关于doxygen函数的完整文档的示例:

/**
 * \brief   The function bar. 
 *
 * \details This function does something which is doing nothing. So this text
 *          is totally senseless and you really do not need to read this,
 *          because this text is basically saying nothing.
 *
 * \note    This text shall only show you, how such a \"note\" section
 *          is looking. There is nothing which really needs your notice,
 *          so you do not really need to read this section.
 *
 * \param[in]     a    Description of parameter a.
 * \param[out]    b    Description of the parameter b.
 * \param[in,out] c    Description of the parameter c.
 *
 * \return        The error return code of the function.
 *
 * \retval        ERR_SUCCESS    The function is successfully executed
 * \retval        ERR_FAILURE    An error occurred
 */

errcode_t bar(int a, int b, int c)
{    
    /** More detailed description inside the code */
}
 

来源和Doxygen主页上的更多信息

安装或设置

有关设置或安装doxygen的详细说明。