doxygen注释
2016-04-08 11:14
330 查看
为代码写注释一直是大多开发人员有些困扰的事情。当前开发人员都能接受为了程序的可维护性、可读性编码的同时写注释的说法,但对哪些地方应该写注释,注释如何写,写多少等这些问题,很多开发人员仍然没有答案。更头痛的是写文档,以及维护文档的问题,开发人员通常可以忍受编写或者改动代码时编写或者修改对应的注释,但之后需要修正相应的文档却比较困难。如果能从注释直接转化成文档,对开发人员无疑是一种福音。而doxygen就能把遵守某种格式的注释自动转化为对应的文档。
Doxygen是基于GPL的开源项目,是一个非常优秀的文档系统,当前支持在大多数unix(包括linux),windows家族,Mac系统上运行,完全支持C++, C, Java, IDL(Corba和Microsoft 家族)语言,部分支持PHP和C#语言,输出格式包括HTML、latex、RTF、ps、PDF、压缩的HTML和unix manpage。有很多开源项目(如log4cpp和CppUnit)都使用了doxygen文档系统。
Doxygen 就是这样的一个工具。在您写批注时,稍微按照一些它所制订的规则。接着,他就可以帮您产生出漂亮的文档了。因此,Doxygen 的使用可分为两大部分。首先是特定格式的批注撰写,第二便是利用Doxygen的工具来产生文件。
Doxygen及相关工具的下载
(1)Doxygen的最新版本,可以从Doxygen的网站下载。
(2)Graphviz是一个图形可视化软件。Doxygen使用Graphviz生成各种图形,例如类的继承关系图、合作图,头文件包含关系图等。可以从Graphviz的网站下载Graphviz的最新版本。
常用指令介绍
[cpp] view
plain copy
/**
* @file testcommnet.h
* @brief
* @author liuxuezong
* @date 2011/8/24 8:37:56
* @version 0.1
* <pre><b>copyright: microsoft</b></pre>
* <pre><b>email: </b>liuxuezong@126.com</pre>
* <pre><b>company: </b>http://www.microsoft.com</pre>
* <pre><b>All rights reserved.</b></pre>
*/
#ifndef _TESTCOMMNET_H_
#define _TESTCOMMNET_H_
/**
* @class CTestCommnet
* @brief一个简单JavaDoc文档注释例子.
*
* 该范例包含枚举、类、函数、变量等注释.
*/
/** 颜色的枚举定义
*
* 该枚举定义了系统中需要用到的颜色\n
* 可以使用该枚举作为系统中颜色的标识
*/
enum TEnum
{
RED, /**< 红色 */
BLUE, /**< 蓝色 */
YELLOW /**< 黄色. */
} enumVar;
class CTestCommnet
{
public:
/**
* @briefConstructor for CTestCommnet.
*
* Detailed description.
*/
CTestCommnet();
/**
* @briefDestructor for CTestCommnet.
*
* Detailed description.
*/
virtual ~CTestCommnet();
public:
/**
* @briefAdd
*
* 通过形参a和b求和.
* @param[in] 形参a
* @param[in] 形参b
* @return int
* @retval 返回a+b的和.
*/
int Add(int a, int b);
protected:
int m_nCount; /**< 计数变量 */
};
#endif // _TESTCOMMNET_H_
[cpp] view
plain copy
#include "testcomment.h"
CTestCommnet::CTestCommnet()
{
m_nCount = 0;
}
CTestCommnet::~CTestCommnet()
{
}
int CTestCommnet::Add(int a, int b)
{
return (a + b);
}
日期:2011/8/24 8:37:56
版本:0.1
颜色的枚举定义
该枚举定义了系统中需要用到的颜色
可以使用该枚举作为系统中颜色的标识
枚举值:
颜色的枚举定义
该枚举定义了系统中需要用到的颜色
可以使用该枚举作为系统中颜色的标识
所有成员的列表。
该范例包含枚举、类、函数、变量等注释.
Constructor for CTestCommnet.
Detailed description.
Destructor for CTestCommnet.
Detailed description.
Add
通过形参a和b求和.
参数:
返回:int
返回值:
计数变量
该类的文档由以下文件生成:
F:/Test/testcommnet.h
F:/Test/testcommnet.cpp
最后,感谢您的阅读,更多细节可以到网上搜索:)
Doxygen是基于GPL的开源项目,是一个非常优秀的文档系统,当前支持在大多数unix(包括linux),windows家族,Mac系统上运行,完全支持C++, C, Java, IDL(Corba和Microsoft 家族)语言,部分支持PHP和C#语言,输出格式包括HTML、latex、RTF、ps、PDF、压缩的HTML和unix manpage。有很多开源项目(如log4cpp和CppUnit)都使用了doxygen文档系统。
Doxygen 就是这样的一个工具。在您写批注时,稍微按照一些它所制订的规则。接着,他就可以帮您产生出漂亮的文档了。因此,Doxygen 的使用可分为两大部分。首先是特定格式的批注撰写,第二便是利用Doxygen的工具来产生文件。
Doxygen及相关工具的下载
(1)Doxygen的最新版本,可以从Doxygen的网站下载。
(2)Graphviz是一个图形可视化软件。Doxygen使用Graphviz生成各种图形,例如类的继承关系图、合作图,头文件包含关系图等。可以从Graphviz的网站下载Graphviz的最新版本。
常用指令介绍
@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 本函数执行可能会产生超出范围的异常 |
plain copy
/**
* @file testcommnet.h
* @brief
* @author liuxuezong
* @date 2011/8/24 8:37:56
* @version 0.1
* <pre><b>copyright: microsoft</b></pre>
* <pre><b>email: </b>liuxuezong@126.com</pre>
* <pre><b>company: </b>http://www.microsoft.com</pre>
* <pre><b>All rights reserved.</b></pre>
*/
#ifndef _TESTCOMMNET_H_
#define _TESTCOMMNET_H_
/**
* @class CTestCommnet
* @brief一个简单JavaDoc文档注释例子.
*
* 该范例包含枚举、类、函数、变量等注释.
*/
/** 颜色的枚举定义
*
* 该枚举定义了系统中需要用到的颜色\n
* 可以使用该枚举作为系统中颜色的标识
*/
enum TEnum
{
RED, /**< 红色 */
BLUE, /**< 蓝色 */
YELLOW /**< 黄色. */
} enumVar;
class CTestCommnet
{
public:
/**
* @briefConstructor for CTestCommnet.
*
* Detailed description.
*/
CTestCommnet();
/**
* @briefDestructor for CTestCommnet.
*
* Detailed description.
*/
virtual ~CTestCommnet();
public:
/**
* @briefAdd
*
* 通过形参a和b求和.
* @param[in] 形参a
* @param[in] 形参b
* @return int
* @retval 返回a+b的和.
*/
int Add(int a, int b);
protected:
int m_nCount; /**< 计数变量 */
};
#endif // _TESTCOMMNET_H_
[cpp] view
plain copy
#include "testcomment.h"
CTestCommnet::CTestCommnet()
{
m_nCount = 0;
}
CTestCommnet::~CTestCommnet()
{
}
int CTestCommnet::Add(int a, int b)
{
return (a + b);
}
F:/Test/testcommnet.h文件参考
组合类型 | |
class | CTestCommnet |
一个简单JavaDoc文档注释例子. 更多... | |
枚举 | |
enum | TEnum {RED,BLUE, YELLOW } |
变量 | |
enum TEnum | enumVar |
详细描述
作者:liuxuezong日期:2011/8/24 8:37:56
版本:0.1
copyright: microsoft
email: liuxuezong@126.com
company: http://www.microsoft.com
All rights reserved.
枚举类型文档
enum TEnum |
该枚举定义了系统中需要用到的颜色
可以使用该枚举作为系统中颜色的标识
枚举值:
RED | 红色 |
BLUE | 蓝色 |
YELLOW | 黄色. |
变量文档
enum TEnum enumVar |
该枚举定义了系统中需要用到的颜色
可以使用该枚举作为系统中颜色的标识
CTestCommnet类参考
一个简单JavaDoc文档注释例子. 更多...#include <testcommnet.h>
所有成员的列表。
公有成员 | |
CTestCommnet () | |
Constructor for CTestCommnet. | |
virtual | ~CTestCommnet () |
Destructor for CTestCommnet. | |
int | Add (int a, int b) |
Add | |
保护属性 | |
int | m_nCount |
详细描述
一个简单JavaDoc文档注释例子.该范例包含枚举、类、函数、变量等注释.
构造及析构函数文档
CTestCommnet::CTestCommnet | ( | ) |
Detailed description.
CTestCommnet::~CTestCommnet | ( | ) | [virtual] |
Detailed description.
成员函数文档
int CTestCommnet::Add | ( | int | a, | |
int | b | |||
) |
通过形参a和b求和.
参数:
[in] | 形参a | |
[in] | 形参b |
返回值:
返回a+b的和. |
成员数据文档
int CTestCommnet::m_nCount[protected] |
该类的文档由以下文件生成:
F:/Test/testcommnet.h
F:/Test/testcommnet.cpp
最后,感谢您的阅读,更多细节可以到网上搜索:)
相关文章推荐
- Yii2使用beforeLogout事件更新用户登录信息
- sort() , sorted() 与argsort()
- 线性判别分析(Linear Discriminant Analysis,LDA)
- 省市区三级下拉选择器
- sql trim
- win server 2008 R2 域控制器安装
- poj 1127 Jack Straws
- 多线程的3中实现方式,以及有返回值线程池Demo
- 完美解决Android SDK Manager无法更新
- 详解spring 每个jar的作用
- enum
- mysql安装卸载乱码等问题
- 认识自己
- leetcode_086 Partition List
- 资源加载问题
- php图片压缩剪裁
- Mysql (一)Mysql 在Linux系统安装
- iOS webservice整理
- 大家从小到大,都玩儿过的一个庸俗的游戏,报到能被7整除的数字,或者尾数是7的数字,就应该罚唱歌。
- Spring Aop相关问题