doxygen使用与C++注释规范

来源：互联网发布：713中美南海对峙知乎编辑：程序博客网时间：2024/06/06 09:25

<div id="article_content" class="article_content tracking-ad" data-mod="popu_307" data-dsm="post">

1.   doxygen的安装与参数配置 
1.1.  安装 
$ sudo apt-get install doxygen 
以下可以选择安装 
$sudo apt-get install doxygen-doc doxygen-gui graphviztexpower dot2tex graphviz-doc texpower-examples 
1.2.  生成配置文件 
在 shell 提示上，输入命令 doxygen -g。这个命令在当前目录中生成一个可编辑的配置文件 Doxyfile。可以改变这个文件名，在这种情况下，应该调用 doxygen -g<user-specified file name> 
1.3.  修改配置参数 
l        <OUTPUT_DIRECTORY>：必须在这里提供一个目录名，例如 /home/user1/documentation，这个目录是放置生成的文档文件的位置。如果提供一个不存在的目录名，doxygen 会以这个名称创建具有适当用户权限的目录。 
l        <INPUT>：这个标记创建一个以空格分隔的所有目录的列表，这个列表包含需要生成文档的 C/C++ 源代码文件和头文件。例如，请考虑以下代码片段： 
INPUT = /home/user1/project/kernel /home/user1/project/memory 
在这里，doxygen 会从这两个目录读取 C/C++ 源代码。如果项目只有一个源代码根目录，其中有多个子目录，那么只需指定根目录并把<RECURSIVE> 标记设置为 Yes。 
l        <FILE_PATTERNS>：在默认情况下，doxygen会搜索具有典型 C/C++ 扩展名的文件，比如 .c、.cc、.cpp、.h 和 .hpp。如果<FILE_PATTERNS> 标记没有相关联的值，doxygen就会这样做。如果源代码文件采用不同的命名约定，就应该相应地更新这个标记。例如，如果项目使用 .c86 作为 C 文件扩展名，就应该在 <FILE_PATTERNS> 标记中添加这个扩展名。 
l        <RECURSIVE>：如果源代码层次结构是嵌套的，而且需要为所有层次上的 C/C++ 文件生成文档，就把这个标记设置为 Yes。例如，请考虑源代码根目录层次结构 /home/user1/project/kernel，其中有/home/user1/project/kernel/vmm 和/home/user1/project/kernel/asm 等子目录。如果这个标记设置为 Yes，doxygen 就会递归地搜索整个层次结构并提取信息。 
l        <EXTRACT_ALL>：这个标记告诉 doxygen，即使各个类或函数没有文档，也要提取信息。必须把这个标记设置为 Yes。 
l        <EXTRACT_PRIVATE>：把这个标记设置为 Yes。否则，文档不包含类的私有数据成员。 
l        <EXTRACT_STATIC>：把这个标记设置为 Yes。否则，文档不包含文件的静态成员（函数和变量）。 
l        <SOURCE_BROWSER>：把这个标记设置为 Yes，自动加入源码。 
  
  
2.   文件注释 
2.1.  示例 
/** 
 * @file apply.c 
 * @author lishujie 
 * @version 1.0 
 * @date 2013-12-12 
 * @brief this brief 
 * @details this's details 
 */ 
2.2.  说明 
l        “@file”后的文件名需与当前文件名一致 
  
3.   结构体注释 
3.1.  简洁样例 
typedef struct Mac_Config                                                               ///  the brief structcomment 
{ 
         charmacaddr[QCT_OTHER_MACADDR_64];            ///< The brief mement comment 
         chardevicename[QCT_OTHER_DEVNAME_64];         ///< The brief mement comment 
         intchecked;                                                                              ///< The brief mement comment 
} Mac_list; 
3.2.  详细样例 
/** 
 * this is details struct 
 */ 
typedef struct DynamicConfigT                                              ///  The brief mementcomment 
{ 
         int     nApplyId;                                                      ///< The brief mement comment 
         int     nTime;                                                                 ///< The brief mement comment 
         int     nReboot;                                                   ///< The brief mement comment 
  
    /** this is details mement comment */ 
         char**  aValTable;                                                        ///< The brief mement comment 
         LocalHndl   pfnHndl;                                              ///< The brief mement comment 
} DynamicConfig; 
3.3.  说明 
l        “///”与注释间留有2个空格 
l        “///<”与注释间留有1个空格 
l        结构体成员的详细注释写在该成员上面 
l        结构体成员的详细注释与上一成员间留1个空行 
l        推荐结构体使用typedef类型定义 
l        推荐使用简洁的结构体注释 
  
4.   枚举注释 
4.1.  样例 
typedef enum _COLOR       ///  The brief enum comment 
{ 
BLACK,                                     ///< The brief member comment 
NAVY,                                  ///< The brief member comment 
}COLOR; 
4.2.  说明 
l        与结构体的简洁注释相同 
  
5.   宏注释 
5.1.  简洁样例 
/// This macro is toolong, so comment here briefly! 
#define HTTP_REQUEST_LEN_MAX    APPLY_BUF_SIZE_BIG 
5.2.  详细样例 
/** 
 * The detail macro comment, may be multi-line. 
 * @param a The brief parameter comment 
 * @param b The brief parameter comment 
 * @return The brief return value comment 
 */ 
#define MAX(a, b) ((a) > (b))? (a) : (b) 
5.3.  说明 
l        尽量少写宏函数，可以使用内联函数代替 
l        推荐使用简洁的宏注释 
  
6.   函数注释 
6.1.  简洁样例 
/// The brieffunction comment, may be multi-line. 
static int apply_login(); 
6.2.  详细样例 
/** 
 * The detail function comment, may bemulti-line. 
 * @param cur_id The brief parameter comment 
 * @return The brief return value comment 
 * @brief The brief function comment 
 */ 
static int reboot_enable( intcur_id ) 
6.3.  说明 
l        简述以///+空格开头或使用@brief ，详述以/**开头 
l        无参无返回值的简单函数使用简洁注释 
l        头文件有声明的函数注释在头文件中；否则注释在代码文件中 
  
7.   其它注释 
l        代码中其余注释一律使用普通的单行注释“//”和多行注释“/*”“*/”。 
  
8.   附录 
8.1.  注释换行 
Doxygen 会忽略你注释中的换行符，将多行注释连接成一个连续行并使用空格隔开。如 
果你希望保留两行注释之间的换行，需要在该行末加入“/n”。 
8.2.  常用命令 
命令 
生成字段名 
说明 
@attention 
注意 
  
@author 
作者 
  
@bug 
缺陷 
链接到所有缺陷汇总的缺陷列表 
@brief 
简要注释 
  
@code 
  
代码块开始，与“nendcode”成对使用 
@details 
详细注释 
  
@date 
日期 
  
@endcode 
  
代码块结束，与“ncode”成对使用 
@file 
< 文件名> 文件参考 
用在文件注释中 
@param 
参数 
用在函数注释中 
@return 
返回 
用在函数注释中 
@todo 
TODO 
链接到所有TODO 汇总的TODO 列表 
@version 
版本 
  
@warning 
警告 
  
8.3.  vim+Doxygen方便的写注释 
8.3.1.   安装 
下载 doxygen的 vim 插件 
   http://www.vim.org/scripts/script.php?script_id=987 
将下载的插件安装到$VIMRUNTIME/plugin目录下 
在VIM的配置文件中(windows下的_vimrc，linux下的vimrc或者~/.vimrc)为doxygentoolkit这个插件配置一些全局变量： 
let g:doxygenToolkit_authorName="your name" 
let g:doxygenToolkit_briefTag_funcName="yes" 
8.3.2.   常用命令 
Dox 
DoxAuthor 
DoxLic 
8.4.  给source insight添加doxygen注释风格 
请参考：http://blog.csdn.net/dayong419/article/details/7932467

</div>

阅读全文

0 0