doxygen–自动生成文档工具

原文地址：doxygen–自动生成文档工具 – 无敌牛

欢迎参观我的个人博客：无敌牛 – 技术/著作/典籍/分享等

简介

doxygen是软件开发中广泛使用的文档生成工具。它可以从源代码注释中自动生成文档，解析类、函数、参数相关信息，并生成 HTML 和 PDF 格式的文档。doxygen 简化了并且标准化了文档生成过程，可以实现跨编程语言和项目来维护管理项目，增强编码协助能力。

官方地址：https://www.doxygen.nl/index.html

示例

拿一个小的开源项目 libucl 做一个测试，libucl的源代码在：GitHub - vstakhov/libucl: Universal configuration library parser

获取代码：git clone https://github.com/vstakhov/libucl.git

生成 doxygen 的配置文件：doxygen -g 。默认在当前目录下生成 Doxyfile 文件。

对文件中的输入和输出配置做个修改

INPUT = src

OUTPUT_DIRECTORY = docs

执行：doxygen 生成文档

进入目录查看生成的文档

搭建简单的网站，查看文档。

可以使用 python3 的 http.server 模块

访问刚搭建的网站，随便点点。

注释简单说明

doxygen支持 C/C++/golang/C#/Java/PHP/Python/Ruby 等很多语言，需要在代码中规范化编写注释就可以实现自动生成文档

C/C++

函数/方法
/**
 * 简短描述。
 *
 * 更详细的描述...
 *
 * @param param1 参数1的说明。
 * @param param2 参数2的说明。
 * @return 返回值的说明。
 */
void myFunction(int param1, float param2);

类/结构体
/**
 * 类的简短描述。
 *
 * 更详细的描述...
 */
class MyClass {
public:
    /**
     * 构造函数的简短描述。
     */
    MyClass();
};

成员变量
/// 简短描述。
int myVariable;

python

模块及注释
"""
Module-level brief description.

This module provides functionality for ...
"""

# Alternatively, you can use single-line comments with specific tags:
# @file my_module.py
# @brief Module-level brief description.

函数/方法
def my_function(param1, param2):
    """
    简短描述。

    更详细的描述...

    :param param1: 参数1的说明。
    :param param2: 参数2的说明。
    :returns: 返回值的说明。
    """
    pass

还需要在 doxygen 的配置文件中设置对 Python 的支持
INPUT                  = ./your-python-source-directory/
FILE_PATTERNS          = *.py
OPTIMIZE_OUTPUT_PYTHON = YES  # Optimize output for Python syntax
EXTRACT_ALL            = YES  # Extract all symbols, not just those with documentation comments

golang

函数/方法
// Short description of the function.
//
// Detailed description of the function, if needed.
// 
// @param param1 Description of the first parameter.
// @param param2 Description of the second parameter.
// @return Description of the return value.
func myFunction(param1 int, param2 string) (int, error) {
    // Function implementation...
}

类型定义（结构体）
// MyStruct is a brief description of the struct.
type MyStruct struct {
    // Field1 is a brief description of this field.
    Field1 int

    // Field2 is a brief description of this field.
    Field2 string
}

使用标记

Doxygen 提供了大量的标记来描述不同的元素，例如参数、返回值、作者等。一些常用的标记包括：