【一键生成项目文档】Doxygen 入门指南

Doxygen 是个什么牛马 ？

---

Doxygen是一款文档生成工具，它可以从带有注释的代码中提取出关键信息，并一键生成各种文档格式（支持的文档格式有：LaTeX、HTML，PDF，RTF、XML、Docbook、Manpage等）。只要你的代码注释符合标准，那么当你代码敲完的时候，文档已经部署完成了

Doxygen不仅仅可以作为文档，还可以作为大型项目的分析手段。它可以生成函数调用，从而帮助理解程序的逻辑关系。

支持的语言：

• C、Objective-C、C#、PHP、Java、Python、IDL（Corba、Microsoft 和 UNO/OpenOffice 风格） )、Fortran、VHDL 以及在某种程度上 D

支持平台：

• Windows
• Linux
• Mac OS X
• 多数Unix发行版本

效果图：（以HTML文档为例）

• 文档
  

• 函数调用关系

  • 每个函数都是超链接，可以点进去，跳转到对应的文档页面
    

• 函数
  

Doxygen的文档功能十分强大，更多的页面在此不一一列举，读者可以自行探索。

Doxygen 的安装

---

打开官网，选择对应的操作系统版本即可

对于Linux版本，可以直接使用sudo apt install doxygen-gui命令安装

Doxygen 的使用

---

以我所使用的Linux系统的Doxygen为例

打开软件后，配置Doxygen项目：

• 指定工作路径
• 指定文档名称、版本号、源码路径、文档路径等信息
• 如下图所示

配置mode：

配置output：

配置diagram：

在expert选项中，可以配置更多的细节：

最后，点击run即可生成文档

注释规范

文档的生成必须要遵守固定的注释规范，

对变量的注释
支持多重注释风格，比如：

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

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

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

在这里比较推荐第三种：通过///<的方式注释

对函数的注释

函数声明/定义之前支持用@param命令，从而生成有文档的注释

按下/*之后，再按下回车，即可生成下面带有@的注释。这些都是自动生成的，十分方便，往里面填空即可

/**
 * @brief 
 * 
 * @note 
 * @param a 
 * @param b 

 * @return int 
 */
int  wdnmd(int a,int b)
{
    return sum;
}

对C++类的注释

对类写下如下注释后，生成的文档见点我查看效果

/*! A test class */
 
class Afterdoc_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 */
};

对文件的注释

该注释应该写在在文件最开始处

/**
 * @file Untitled-1
 * @author your name (you@domain.com)
 * @brief 
 * @version 0.1
 * @date 2022-01-08
 * 
 * @copyright Copyright (c) 2022
 * 
 */

更多信息

可以访问官网查看：https://www.doxygen.nl/index.html