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 提供了大量的标记来描述不同的元素，例如参数、返回值、作者等。一些常用的标记包括：