【Bash百宝箱】doxygen

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