Doxygen 是支持多种语言的文档生成工具。也许在编码前能把设计文档写好，再来编写代码是正确的一件事情，当由于中间编码过程中任务的修改或者代码的优化等原因，会导致开始所写的文档变动非常大，于是在编码前写好文档对于大多数程序员是不太现实的。而在代码写完之后再补上相应的文档则是一件非常常见的做法。Doxygen 就能很好的帮你做好这件事件，在你的代码按照Doxygen 的格式写好注释后，几分钟Doxygen 就能够很快地为你生成文档。最近要使用Doxygen 也是因为代码变多后，之前写的函数往往名字都不记得了，如果能有一份文档查询相应的函数会非常方便。（值得一提的是Hadoop 支持了Doxygen 文档的生成）

一、安装

在官网下载Doxygen ，然后./config 生成Makefile 文件，make， make install 即可。需要注意的是：

先需要下载好相应的工具：

1. GNU 工具flex，bison，GNU make 和strip
2. 需要perl 生成makefile 文件
3. 需要UNIX tools 的常用工具：sed, date, find, uname, mv, cp, cat, echo, tr, cd, 和 rm

如果你下载的是安装文件（bin），./configure 不会检查这些工具是否缺失，因为如果缺少了这些文件则会报make 中间过程的错误。但如果下载的是源代码文件（src），其中的./configure 会检查相应的工具是否存在，因为建议下载源代码文件编译后安装。

 

二、Doxygen 配置

进入所在项目的目录后，可以使用doxygen -g 生成配置文件Doxygen，打开该目录下的配置文件Doxyfile，有相关的配置信息：

DOXYFILE_ENCODING      = UTF-8      文档编码方式，GB2312可以更好支持中文

PROJECT_NAME                  =                  项目名称

PROJECT_NUMBER             =                 项目编号

PROJECT_BRIEF                  =                 项目简介

PROJECT_LOGO                   =                 项目LOGO

OUTPUT_DIRECTORY         = doc/         项目文档默认位置

CREATE_SUBDIRS               = NO           创建4096 个子目录保存生成文件，适合大项目

OUTPUT_LANGUAGE          = English     语种，Chinese/Chinese-Traditional 也支持

BRIEF_MEMBER_DESC     = YES          YES（默认）将每个函数或者类的简述加在前面

OPTIMIZE_OUTPUT_FOR_C  = NO     只是C 文档选YES

QUIET                                     = YES          如果出现错误，不中断

FILE_PATTERNS                   = *.h           只对.h 头文件生成

RECURSIVE                            = YES         递归虚幻当前目录子目录

GENERATE_LATEX               = NO          不生成latex 文档

GENERATE TREEVIEW       ＝ALL          文档左侧生成一个侧栏显示类、文件和包关系

配置完后直接 doxygen 就可以生成对应文档了。或者doxygen confile 针对配置问津confile 生成文档。

 

三、为代码撰写评论（comments）

  总体来说有三类评论（comments）：详细评论（detailed comments）；简要评论（brief comments）和函数内评论（body comments）。对于不同类型的评论有不同的方法。

1、详细评论

下面是详细评论的几种方法

/**
 * ... comments ...
 */

/*!
 * ... comments ...
 */

/*!
 ... comments ...
*/

///
/// ... comments ...
///

//!
//!... comments ...
//!

2、简要评论

下面是几种简要评论的几种方法

/*! \brief Brief description.
 *         Brief description continued.
 *
 *  Detailed description starts here.
 */

/** Brief description which ends at this dot. Details follow
 *  here.
 */

/// Brief description which ends at this dot. Details follow
/// here.

/// Brief description.
/** Detailed description. */

//! Brief description.

//! Detailed description 
//! starts here.

//! Brief description, which is
//! really a detailed description since it spans multiple lines.
/*! Another detailed description!
 */

3、函数内评论

下面是几种函数内评论

int var; /*!< Detailed description after the member */

int var; /**< Detailed description after the member */

int var; //!< Detailed description after the member
         //!< 

int var; ///< Detailed description after the member
         ///< 

int var; //!< Brief description after the member

int var; ///< Brief description after the member

void foo(int v /**< [in] docs for input parameter v. */);

下面是一个完整的例子：

/*! A test class */
class Test
{
  public:
    /** An enum type. 
     *  The documentation block cannot be put after the enum! 
     */
    enum EnumType
    {
      int EVal1,     /**< enum value 1 */
      int EVal2      /**< enum value 2 */
    };
    void member();   //!< a member function.
    
  protected:
    int value;       /*!< an integer value */
};

通过@param 可以在块(函数)注释中添加输入类型和定义, @return 定义返回值

 

四、为html 安装apache

1. sudo apt-get install apache2
2. 修改/etc/apache2/apache2.conf 配置文件（可选，参考这里）
3. 修改/etc/apache2/sites-endabled/ 中DocumentRoot 和主目录为自己html 文档生成的地方
4. sudo service apache2 restart

这样通过网页方式可以查看到自己生成的文档了~~

 

 

参考资料：

【1】Doxygen 配置文件说明

【2】Doxygen 官网

【3】Doxygen 语法