Windows环境下代码文档生成工具Doxygen使用详细教程

news2024/11/23 1:13:07

背景

最近研究aom源码，发现编译需要依赖Doxygen工具，故此篇博客详细记录下Doxygen的安装和使用。

Doxygen

Doxygen 是一个强大的源代码文档生成工具，它支持多种编程语言，能够直接从源代码中的注释提取文档，并生成多种格式的文档，包括 HTML、PDF、RTF、LaTeX、Man 页等。下面是关于 Doxygen 的一些关键特性和使用方法：

多语言支持：Doxygen 支持 C++, C, Java, Objective-C, Python, Fortran, VHDL 等多种编程语言。
注释解析：Doxygen 能够解析源代码文件中的特殊注释格式，这些注释需要用 \ 或 /** 开头。
文档生成：可以根据注释生成结构化的文档，包括函数、类、变量、文件等的详细描述。
自定义：用户可以自定义输出的文档样式，包括 HTML 主题、布局、颜色等。
图形生成：能够自动生成代码中的类图、协作图、继承图等。
配置文件：使用 Doxyfile 配置文件来控制 Doxygen 的行为，包括要解析的源文件、输出格式、文档结构等。
版本控制集成：可以与 Git 等版本控制系统集成，以提供源代码的版本信息。
搜索功能：生成的 HTML 文档包含搜索功能，方便用户查找特定的类、函数或变量。

高级特性：

条件编译：Doxygen 支持条件编译指令，允许在特定条件下包含或排除文档块。
文档分离：可以将文档和源代码分离，使得代码更简洁，同时文档更完整。
图形和图表：可以生成复杂的图形，如流程图、状态图、序列图等。

Doxygen 是一个非常灵活和强大的工具，适用于任何规模的项目。通过适当的配置和使用，它可以帮助开发者提高文档的质量和可维护性。

基本使用

官网下载：https://www.doxygen.nl/download.htm
安装
软件界面介绍

注释格式

Doxygen 使用特定的注释格式来提取文档信息。以下是一些常用的注释标记：

\brief：为成员函数或变量提供简短描述。
\param：描述函数参数。
\return：描述函数返回值。
\author：标明作者信息。
\version：提供版本信息。
\see：提供相关函数或文档的引用。
\code 和 \endcode：标记代码段。

示例

编写测试项目

.
├── out
└── src
    └── add.cpp

add.cpp 文件内容

/*! \file add.cpp */

/*!
  \li Calculate the sum of two numbers.
 
  \li This function takes two integers and returns their sum.
 
  \param a The first integer.
  \param b The second integer.
  \return The sum of the two integers.
 */
int add(int a, int b){
    return a + b;
}

/**
   \li 程序入口函数
   
   \param 无参数
   
   \return 0
 */
int main()
{
    int x = 10;
    int y = 100;
    int ret = add(10, 100);

    std::cout << "the sum of two numbers: " << ret << std::endl;

    return 0;
}