1、简介
doxygen是一个用于多种编程语言的文档系统,支持C++
、C
、Java
、Objective-C
、Corba和Microsoft风格的IDL
、PHP
、C#
、D
等。在Linux下,doxygen是一个命令行工具,另外还有一个GUI工具doxywizard,下面简单介绍doxygen的用法。
2、配置文件
在Linux shell执行如下命令,其中-g
表示生成配置文件,-s
表示配置文件中不保留注释代码,MyDoxyfile表示生成的配置文件名。
$ doxygen -g -s MyDoxyfile
然后对MyDoxyfile这个配置文件稍作修改,PROJECT_NAME
表示工程名,OUTPUT_DIRECTORY
表示doxygen生成结果的输出目录,INPUT表示带有doxygen注释的文件或目录,其它配置可根据需要进行修改。
PROJECT_NAME = "DoxygenTest"
OUTPUT_DIRECTORY = doxygen
INPUT = source
3、注释
doxygen注释有不同的风格,如下面例子中foo.h
的JavaDoc
风格和bar.h
的Qt
风格,具体包括了file、brief与详细描述、宏、typedef
、变量、函数、namespace
、class
、struct
、enum
、union
等,这两大风格也可以有不同的写法。
JavaDoc style——
//foo.h
/**
* @file foo.h
* @brief The doxygen style is JavaDoc.
*
* It consists of a C-style comment block starting with two *'s.
*/
///
/// FOO macro
///
#define FOO "foo"
///
/// fint typedef
///
typedef int fint;
int foo1 = 1; /**< foo1 with detailed description */
int foo2 = 2; ///< foo2 with detailed description
///<
int foo3 = 3; ///< foo3 with brief description
/**
* fooFunc function #FOO
* @param f[in] input an integer
* @return return an integer
* @sa foo1 foo2 foo3
*/
int fooFunc(int f);
///
/// foo namespace
///
namespace foo
{
/**
* FooClass class
*/
class FooClass
{
};
/**
* FooStruct struct
*/
struct FooStruct
{
};
/**
* FooEnum enum
*/
enum FooEnum
{
};
/**
* FooUnion union
*/
union FooUnion
{
};
}
Qt style——
//bar.h
/*!
* \file bar.h
* \brief The doxygen style is Qt.
*
* Add an exclamation mark (!) after the opening of a C-style comment block.
*/
//!
//! BAR macro
//!
#define BAR "bar"
//!
//! bint typedef
//!
typedef int bint;
int bar1 = 1; /*!< bar1 with detailed description */
int bar2 = 2; //!< bar2 with detailed description
//!<
int bar3 = 3; //!< bar3 with brief description
/*!
* barFunc function with #BAR
* \param b[in] input an integer
* \return return an integer
* \see bar1 bar2 bar3
*/
int barFunc(int b);
//!
//! bar namespace
//!
namespace bar {
/*!
* BarClass class
*/
class BarClass
{
};
/*!
* BarStruct struct
*/
struct BarStruct
{
};
/*!
* BarEnum enum
*/
enum BarEnum
{
};
/*!
* BarUnion union
*/
union BarUnion
{
};
}
4、生成
在Linux shell通过如下命令生成doxygen结果,根据前面的配置文件,结果为html
形式,当然还支持其它形式,结果就不在这里贴图了。
$ doxygen MyDoxyfile
5、高级
上面只是个简单的示例,doxygen还支持Markdown、Lists、Groups、公式、表格、图等,更多内容可参照http://www.stack.nl/~dimitri/doxygen/manual/index.html