Doxygen——根据代码注释生成文档的工具

1 简介

Doxygen是一个可以根据代码注释生成文档的工具，支持HTML、CHM、LaTex等格式。主要支持C语言、Python语言，还支持C++、Java、C#等语言。

通常我们在写程序时，或多或少都会写上注释，但是对于其它人而言，要直接探索程序里的注释会比较麻烦。大部分有用的注释都是属于对函数、类型等的说明。所以，如果能依据程序本身的结构，将注释经过处理重新整理成为一个纯粹的参考手册，对于后面利用此程序代码的人而言将会减少许多负担。

2 安装

sudo apt install doxygen
sudo apt install doxygen-gui

其中，doxygen使用命令行操作，doxygen-gui是doxygen的图形用户界面。

3 使用

3.1 注释代码

Doxygen能识别这几种风格的注释：

/**
 * ... text ...
 */

/*!
 * ... text ...
 */

///
/// ... text ...
///

//!
//!... text ...
//!

文件的开头必须有文件注释，否则该文件不会被识别：

/** @file */ 

结构化命令可以识别代码块的含义，主要包括：

• \class to document a class.
• \struct to document a C-struct.
• \union to document a union.
• \enum to document an enumeration type.
• \fn to document a function.
• \var to document a variable or typedef or enum value.
• \def to document a #define.
• \typedef to document a type definition.
• \file to document a file.
• \namespace to document a namespace.
• \package to document a Java package.
• \interface to document an IDL interface.
• @todo things to be done.

其中，\可以替换为@，即\class等价于@class。

具体怎么写注释？可以直接看一个使用Javadoc风格的C++代码文档的例子：

/**
 *  A test class. A more elaborate class description.
 */
 
class Javadoc_Test
{
  public:
 
    /** 
     * An enum.
     * More detailed enum description.
     */
 
    enum TEnum { 
          TVal1, /**< enum value TVal1. */  
          TVal2, /**< enum value TVal2. */  
          TVal3  /**< enum value TVal3. */  
         } 
       *enumPtr, /**< enum pointer. Details. */
       enumVar;  /**< enum variable. Details. */
       
      /**
       * A constructor.
       * A more elaborate description of the constructor.
       */
      Javadoc_Test();
 
      /**
       * A destructor.
       * A more elaborate description of the destructor.
       */
     ~Javadoc_Test();
    
      /**
       * a normal member taking two arguments and returning an integer value.
       * @param a an integer argument.
       * @param s a constant character pointer.
       * @see Javadoc_Test()
       * @see ~Javadoc_Test()
       * @see testMeToo()
       * @see publicVar()
       * @return The test results
       */
       int testMe(int a,const char *s);
       
      /**
       * A pure virtual member.
       * @see testMe()
       * @param c1 the first argument.
       * @param c2 the second argument.
       */
       virtual void testMeToo(char c1,char c2) = 0;
   
      /** 
       * a public variable.
       * Details.
       */
       int publicVar;
       
      /**
       * a function variable.
       * Details.
       */
       int (*handler)(int a,int b);
};

单击此处查看由doxygen生成的相应HTML文档。

Doxygen也支持C和Python等编程语言的注释，用法可以参考此链接。

3.2 使用doxywizard生成文档

安装完成doxygen和doxygen-gui后，在终运行doxywizard命令启动Doxygen GUI。作为初学者，可以先使用Doxygen GUI熟悉doxygen的使用方法。

doxywizard的用法参考此链接，主要包括三个步骤：

1. 设置Wizard
2. 设置Expert
3. Run

Wizard页面包括：

• 设置项目，包括项目的名称，源代码路径和生成文档的路径
• 设置模式，更好地匹配编程语言
• 设置输出文件的格式
• 设置生成的图表

Expert页面包括很多高级的设置，要根据自己的实际需求调整。例如，我在注释Apollo项目中的类的私有成员函数时，输出的文档中并没有显示该信息，原因是没有选中Expert下Build中的EXTRACT_PRIVATE。

在Run页面点击Run doxygen按钮，窗口会输出日志信息，如果最后显示Doxygen has finished，则表明运行成功。

最后，点击Show HTML output，会使用浏览器打开将代码文档化的网页。

4 用例

4.1 OpenCV

OpenCV等开源库很好的使用了Doxygen，可以直接看文档和代码感受一下：

• https://docs.opencv.org/3.2.0/d2/d28/calib3d_8hpp.html
• https://github.com/opencv/opencv/blob/master/modules/calib3d/include/opencv2/calib3d.hpp

当然，OpenCV是一个优秀的开源库，内容多且详细，我们可以根据自己项目的实际情况制定一套规则。

4.2 Apollo

目前Apollo部分代码也使用了Doxygen，例如：

• https://github.com/ApolloAuto/apollo/blob/master/modules/common/math/kalman_filter.h

但是还没完全覆盖整个项目，Apollo 6.0计划推出在线的文档，大概率就是用这个工具生成的。

此外，Apollo的cyber模块更多的使用了doxygen。

cd /apollo/cyber/doxy-docs/
./build_doxy_sphinx.sh

安装相关依赖：

pip install sphinx breathe recommonmark -i https://pypi.tuna.tsinghua.edu.cn/simple

运行脚本：

./build_doxy_sphinx.sh

然后，打开/apollo/cyber/doxy-docs/build/html中任意一个html文件即可。

注：这种打开html文件的方法不是很优雅，因为我对doxygen的操作还不是很熟悉。

5 参考

• https://www.doxygen.nl/index.html
• https://docs.opencv.org/3.2.0/d2/d28/calib3d_8hpp.html
• https://github.com/opencv/opencv/blob/master/modules/calib3d/include/opencv2/calib3d.hpp
• https://github.com/ApolloAuto/apollo/blob/master/modules/common/math/kalman_filter.h
• https://baike.baidu.com/item/Doxygen/1366536?fr=aladdin