doxygen–自动生成文档工具

doxygen–自动生成文档工具

简介

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

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

示例

拿一个小的开源项目 libucl 做一个测试,libucl的源代码在:https://github.com/vstakhov/libucl

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

  • @param\param:描述函数或方法的参数。
  • @return\return:描述函数或方法的返回值。
  • @brief\brief:提供一个简短的描述。
  • @see\see:引用其他函数、类或文件。
  • @author\author:指定代码的作者。
  • @file\file:为整个文件添加描述。
  • @warning\warning:给出警告信息。
  • @note\note:提供额外的注意事项。
  • @deprecated\deprecated:标识已废弃的功能。

评论

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注