使用JavaDoc风格注释让doxygen自动生成文档

时间：2021-06-30 10:56:42
       为代码写注释一直是大多开发人员有些困扰的事情。当前开发人员都能接受为了程序的可维护性、可读性编码的同时写注释的说法，但对哪些地方应该写注释，注释如何写，写多少等这些问题，很多开发人员仍然没有答案。更头痛的是写文档，以及维护文档的问题，开发人员通常可以忍受编写或者改动代码时编写或者修改对应的注释，但之后需要修正相应的文档却比较困难。如果能从注释直接转化成文档，对开发人员无疑是一种福音。而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的最新版本。

        常用指令介绍

@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 本函数执行可能会产生超出范围的异常

 
/**
* @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:
	/** 
	* @brief Constructor for CTestCommnet.
	* 
	* Detailed description.
	*/
	CTestCommnet();

	/** 
	* @brief Destructor for CTestCommnet.
	* 
	* Detailed description.
	*/
	virtual ~CTestCommnet();

public:
	/** 
	* @brief Add 
	* 
	* 通过形参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_

 

#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 (    )   

Constructor for CTestCommnet.

Detailed description.

CTestCommnet::~CTestCommnet (    )  [virtual]

Destructor for CTestCommnet.

Detailed description.

成员函数文档

int CTestCommnet::Add ( int  a,
    int  b  
  )      

Add

通过形参a和b求和.

参数:
[in]  形参a   
[in]  形参b   
返回:
int
返回值:
  返回a+b的和.   

成员数据文档

int CTestCommnet::m_nCount [protected]

计数变量

该类的文档由以下文件生成：

 最后，感谢您的阅读，更多细节可以到网上搜索:)

标签：

相关文章