本节概述了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的详细说明。