Doxygen语法¶

doxygen是一种可以对源码注释进行提取，生成文档的工具。doxygen定义了一套注释标准，只要按照这套标准进行注释，就能正确导出文档，支持的文档格式有html，latex；支持的语言有c，c++，java，python等等主流语言。以下是一简短注释示例

/**
 * @brief 2个整形数据相加
 * 
 * @param x 输入参数1
 * @param[in] y 输入参数2
 * @return int 
 */
int add(int x, int y)
{
  return x + y;
}

1 注释块格式¶

考虑到有些注释不需要导出，为了区分那些需要导出那些不需要导出，doxygen再原先注释块规则上加上额外标志用于区分。

1.1 单行注释¶

标准注释用双斜杠//作为单行注释,doxygen使用3斜杠///或用双斜杠加1个感叹号//!。 - 标准注释如下

//全局变量i
int i=2;

doxygen注释如下

//!全局变量i
int i=2;
///全局变量j
int j=2;

1.2 块注释¶

标准快注释是/*注释*/包裹，而doxygen依然提供2种方式，/**注释*/或/*!注释*/，与标准注释相比多了一个*或!。 - 标准注释如下

/*
 * @brief 2个整形数据相加
 * 
 * @param x 输入参数1
 * @param[in] y 输入参数2
 * @return int 
 */
int add(int x, int y)
{
  return x + y;
}

doxygen注释如下

/**
 * @brief 2个整形数据相加
 * 
 * @param x 输入参数1
 * @param[in] y 输入参数2
 * @return int 
 */
int add(int x, int y)
{
  return x + y;
}

或者

/*!
 * @brief 2个整形数据相加
 * 
 * @param x 输入参数1
 * @param[in] y 输入参数2
 * @return int 
 */
int add(int x, int y)
{
  return x + y;
}

1.3 注释在源码之后¶

doxygen默认是源码前的注释作为此源码的注释，当注释尾随源码时，这段注释就成为下一段源码的注释了，为了区分此类情况，doxygen提供了<符号来标注此注释属于前一源码。 - 单行注释：///<注释 - 块注释：/**<注释*/or/*!<注释*/

int i=2;///<全局变量i
//or
int j=2;/**<全局变量j*/

2 特殊指令¶

doxygen提供了一系列指令来标记类，函数，变量，参数，返回值，异常...，这些特殊命令有很多。命令以@或\开头，如@file或\file表示文件，以下仅列举重要的常用的。 注意：语法形式列表中 - [option]：可选 - <singleword>：仅允许单个单词，即单词不能出现空格 - (lineword)：表示lineword是一行，范围：在行尾结束 - {paragraph}：表示一段信息，范围：在下一个指令前结束或一空行处结束 - 命令列@也可以换成\

2.1 文档头注释¶

指令	语法形式	说明
`@file`	`@file [<name>]`	文件名，当文件名忽略，默认是当前文件
`@author`	`@author { list of authors }`	作者信息
`@date`	`@date { date description }`	创建日期
`@brief`	`@brief { brief description }`	简要说明
`@details`	`@details { detailed description }`	详细说明
`@version`	`@version { version number }`	版本信息
`@copyright`	`@copyright { copyright description }`	知识版权信息

示例如下

 /*! 
 *  \brief     Pretty nice class.
 *  @class SomeNiceClass 
 *  \details   This class is used to demonstrate a number of section commands.
 *  \author    John Doe
 *  \author    Jan Doe
 *  \version   4.2.1
 *  \date      1990-2011
 *  \pre       First initialize the system.
 *  \bug       Not all memory is freed when deleting an object of this class.
 *  \warning   Improper use can crash your application
 *  \copyright GNU Public License.
 */

2.2 函数相关指令¶

指令	语法形式	说明
`@param`	`@param '['dir']' { parameter description }`	参数信息，dir可以是in,out
`@return`	`@return { description of the return value }`	返回值信息
`@throw`	`@throw <exception-object> { exception description }`	异常信息

示例如下

/*!
 * @brief  Copies bytes from a source memory
 * @details Copies bytes from a source memory area to a destination memory area,
 * where both areas may not overlap.
 * @param[out] dest The memory area to copy to.
 * @param[in]  src  The memory area to copy from.
 * @param[in]  n    The number of bytes to copy
 * @return void     no return value
 * @throw std::out_of_range parameter is out of range.
 */
void memcpy(void *dest, const void *src, size_t n);

2.3 其它特殊指令¶

指令	语法形式	说明
`@code`	`@code['{''}']`	代码片段,以@code开始，以@endcode结束
`@todo`	`@todo { paragraph describing what is to be done }`	TODO注释
`@warning`	`@warning { warning message }`	警告信息
`@attention`	`@attention { attention text }`	注意信息，与@warning类似
`@note`	`@note { text }`	注释信息

@code示例

/**
  \code{.py}
  class Python:
     pass
  \endcode

  \code{.cpp}
  class Cpp {};
  \endcode
    \code{.unparsed}
  Show this as-is please
  \endcode

  \code{.sh}
  echo "This is a shell script"
  \endcode
*/

示例2

/**
 * @brief 2个整形数据相加
 * 
 * @param[in] y 输入参数2
 * @todo  paragraph describing what is to be done 
 * @warning this is a warning
 * @attention this is a attention
 * @note this is a note
 * @return int 
 */
int add(int x/**<输入参数1*/, int y);

2.4 标注类，函数，枚举等指令¶

doxygen可以通过如@fn指令指定函数名，然后将注释放入其它位置（即不在此函数前），doxygen依然能将此注释关联到此函数. - @class - @fn - @enum - @file

 /* A dummy class */

 class Test
 {
 };

 /*! \class Test class.h "inc/class.h"
  *  \brief This is a test class.
  *
  * Some details about the Test class.
  */

3 问题汇总¶

在官网有大量问题及解答，请移步官网