使用doxygen从c++代码中生成文档的方法学习 .
2013-01-03 16:22
585 查看
常用的指令说明:
一 概述
C++的注释风格主要使用下面这种样式:即在注释块开始使用三个反斜杠‘/’
其他地方其实与JavaDoc的风格类似,只是C++风格不用 “*” 罢了。
二 简述与详述
C++风格的简述与详述方式与javaDoc类似。
一般注释的描述由简述开始,经过特殊分隔方式后,后面紧跟详述的内容,C++风格可以使用的分隔方法有以下两种:
(1)使用 /brief 参数标识,空行作为简述和详述的间隔标识
/// /brief Brief description. /// description continued. /// /// Detailed description starts here. /// (2) 使用以空行(或者小数点加空格)作为简述与详述的分割
/// Brief description /// description continued. /// /// Detailed description starts here. 以小数点加空格作为分隔如下:
/// Brief description /// description continued . (注意:这里有一个小数点,加上一个空格) /// Detailed description starts here. ///
三 注释风格约定
1. 一个代码块(类、函数、结构等)的概述采用单行的”///”加一个空格开头的注释,并写在该代码块声明的前面;
2. 一个代码块的详述采用至少两行的”///”加一个空格开头的注释,若不足两行第二行的开头也要写出来,并且放在代码块定义的前面;如果某代码没有声明只有定义或者相反,则在定义或者声明前面写上单行的概述+一个空行+多行的详述;
3. 枚举值列表的各项、结构域的各项等采用在本行最后添加”///<”加一个空格开头的注释;
4. 对变量的定义采用在变量上面加单行”///”加一个空格开头的注释(相当于是给改变量一个概述);
5. 函数的参数用”/// @param”+一个空格开头的行描述在函数的详述里面;
6. 函数的返回值用”/// @return”+一个空格开头的行描述在函数的详述里面;
7. 函数之间的参考用”/// @see”+一个空格开头的行描述在函数的详述里面;
8. 文件头的版权以及文件描述的注释参见例代码。
四 文件头注释示例
////////////////////////////////////////////////////////////////////////// /// COPYRIGHT NOTICE /// Copyright (c) 2009, 华中科技大学 (版权声明) /// All rights reserved. /// /// @file (本文件的文件名eg:Test.h) /// @brief(本文件实现的功能的简述) /// ///(本文件实现的功能的详述) /// /// @version 1.1
(版本声明) /// @author (作者,eg:卢俊) /// @date (文件创建日期,eg:2009年7月15日) /// /// /// 修订说明:最初版本 ////////////////////////////////////////////////////////////////////////// 五 类定义注释示例
/// 本类的功能:打印错误信息 /// /// 本类是一个单件 /// 在程序中需要进行错误信息打印的地方 class CPrintError { …… } 5.4.6 类成员变量定义示例
(1)在成员变量上面加注释的格式
/// 成员变量描述 int m_Var; (2)在成员变量后面加注释的格式 int m_color; /// 颜色变量 5.4.7 成员函数的注释示例
/// 下面是一个含有两个参数的函数的注释说明(简述) /// /// 这里写该函数的详述信息 /// @param a 被测试的变量(param描述参数) /// @param s 指向描述测试信息的字符串 /// @return 测试结果 (return描述返回值) /// @see Test() (本函数参考其它的相关的函数,这里作一个链接) /// @note (note描述需要注意的问题) int testMe(int a,const char *s); 5.4.8 枚举变量的注释示例
/// 颜色的枚举定义 /// /// 该枚举定义了系统中需要用到的颜色/n /// 可以使用该枚举作为系统中颜色的标识 enum TEnum { RED, ///< 枚举,标识红色 BLUE, ///< 枚举,标志蓝色 YELLOW ///< 枚举,标志***. }enumVar;
六 需要注意的问题
(1)Doxygen会忽略你在注释中加入的多余的换行,如果你希望保留两行注释之间的空行,那么,在该行加入 /n
原文地址
http://blog.csdn.net/bruce_wang_janet/article/details/6174105
@file | 档案的批注说明。 |
@author | 作者的信息 |
@brief | 用于class 或function的简易说明 eg: @brief 本函数负责打印错误信息串 |
@param | 主要用于函数说明中,后面接参数的名字,然后再接关于该参数的说明 |
@return | 描述该函数的返回值情况 eg: @return 本函数返回执行结果,若成功则返回TRUE,否则返回FLASE |
@retval | 描述返回值类型 eg: @retval NULL 空字符串。 @retval !NULL 非空字符串。 |
@note | 注解 |
@attention | 注意 |
@warning | 警告信息 |
@enum | 引用了某个枚举,Doxygen会在该枚举处产生一个链接 eg: @enum CTest::MyEnum |
@var | 引用了某个变量,Doxygen会在该枚举处产生一个链接 eg: @var CTest::m_FileKey |
@class | 引用某个类, 格式:@class <name> [<header-file>] [<header-name>] eg: @class CTest "inc/class.h" |
@exception | 可能产生的异常描述 eg: @exception 本函数执行可能会产生超出范围的异常 |
C++的注释风格主要使用下面这种样式:即在注释块开始使用三个反斜杠‘/’
其他地方其实与JavaDoc的风格类似,只是C++风格不用 “*” 罢了。
二 简述与详述
C++风格的简述与详述方式与javaDoc类似。
一般注释的描述由简述开始,经过特殊分隔方式后,后面紧跟详述的内容,C++风格可以使用的分隔方法有以下两种:
(1)使用 /brief 参数标识,空行作为简述和详述的间隔标识
/// /brief Brief description. /// description continued. /// /// Detailed description starts here. /// (2) 使用以空行(或者小数点加空格)作为简述与详述的分割
/// Brief description /// description continued. /// /// Detailed description starts here. 以小数点加空格作为分隔如下:
/// Brief description /// description continued . (注意:这里有一个小数点,加上一个空格) /// Detailed description starts here. ///
三 注释风格约定
1. 一个代码块(类、函数、结构等)的概述采用单行的”///”加一个空格开头的注释,并写在该代码块声明的前面;
2. 一个代码块的详述采用至少两行的”///”加一个空格开头的注释,若不足两行第二行的开头也要写出来,并且放在代码块定义的前面;如果某代码没有声明只有定义或者相反,则在定义或者声明前面写上单行的概述+一个空行+多行的详述;
3. 枚举值列表的各项、结构域的各项等采用在本行最后添加”///<”加一个空格开头的注释;
4. 对变量的定义采用在变量上面加单行”///”加一个空格开头的注释(相当于是给改变量一个概述);
5. 函数的参数用”/// @param”+一个空格开头的行描述在函数的详述里面;
6. 函数的返回值用”/// @return”+一个空格开头的行描述在函数的详述里面;
7. 函数之间的参考用”/// @see”+一个空格开头的行描述在函数的详述里面;
8. 文件头的版权以及文件描述的注释参见例代码。
四 文件头注释示例
////////////////////////////////////////////////////////////////////////// /// COPYRIGHT NOTICE /// Copyright (c) 2009, 华中科技大学 (版权声明) /// All rights reserved. /// /// @file (本文件的文件名eg:Test.h) /// @brief(本文件实现的功能的简述) /// ///(本文件实现的功能的详述) /// /// @version 1.1
(版本声明) /// @author (作者,eg:卢俊) /// @date (文件创建日期,eg:2009年7月15日) /// /// /// 修订说明:最初版本 ////////////////////////////////////////////////////////////////////////// 五 类定义注释示例
/// 本类的功能:打印错误信息 /// /// 本类是一个单件 /// 在程序中需要进行错误信息打印的地方 class CPrintError { …… } 5.4.6 类成员变量定义示例
(1)在成员变量上面加注释的格式
/// 成员变量描述 int m_Var; (2)在成员变量后面加注释的格式 int m_color; /// 颜色变量 5.4.7 成员函数的注释示例
/// 下面是一个含有两个参数的函数的注释说明(简述) /// /// 这里写该函数的详述信息 /// @param a 被测试的变量(param描述参数) /// @param s 指向描述测试信息的字符串 /// @return 测试结果 (return描述返回值) /// @see Test() (本函数参考其它的相关的函数,这里作一个链接) /// @note (note描述需要注意的问题) int testMe(int a,const char *s); 5.4.8 枚举变量的注释示例
/// 颜色的枚举定义 /// /// 该枚举定义了系统中需要用到的颜色/n /// 可以使用该枚举作为系统中颜色的标识 enum TEnum { RED, ///< 枚举,标识红色 BLUE, ///< 枚举,标志蓝色 YELLOW ///< 枚举,标志***. }enumVar;
六 需要注意的问题
(1)Doxygen会忽略你在注释中加入的多余的换行,如果你希望保留两行注释之间的空行,那么,在该行加入 /n
原文地址
http://blog.csdn.net/bruce_wang_janet/article/details/6174105
相关文章推荐
- 使用doxygen从c++代码中生成文档的方法学习 .
- 使用doxygen从c++代码中生成文档的方法学习
- Ubuntu 下使用 doxygen 生成C/C++代码文档
- linux c/c++ 代码使用 doxygen 自动生成文档
- 使用Doxygen为C\C++代码写文档
- Linux下使用doxygen+vim生成c语言源程序文档的方法
- 使用Doxygen来自动化生成项目代码文档
- 学习使用 doxygen 生成源码文档
- 使用doxygen为C/C++程序生成中文文档
- 使用doxygen为C/C++程序生成中文文档
- JIN学习一、Android使用已有C/C++代码、第三方SO库的方法
- 【转】使用doxygen为C/C++程序生成中文文档(上)
- 使用doxygen为C/C++程序生成中文文档
- 使用doxygen为C/C++程序生成中文文档(上)
- 使用Doxygen软件将程序代码自动生成chm格式帮助文档
- 使用Doxygen生成代码文档
- 使用Doxygen生成代码文档
- 使用doxygen为C/C++程序生成中文文档
- 使用doxygen生成代码工程文档并显示相关注释
- 使用doxygen为C/C++程序生成中文文档(上)