夜雨聆风软件安装
sudo apt install doxygen graphviz texlive-full latexmkdoxygen c语言注释规范
Doxygen是C/C++项目最常用的自动生成API文档工具，遵循统一注释规范，能一键生成清晰、专业的 HTML/PDF/CHM 文档。
一、注释格式
1. 块注释
/** * 这里是注释内容 */2. 行注释
/// 这是一行注释二、文件头注释（.c/.h 文件顶部）
每个 .h 头文件必须写，.c文件可选。
/** * @file demo.h * @brief 模块功能简要说明（如：GPIO驱动模块、串口通信库） * @details 详细描述模块功能、使用限制、依赖、核心流程 * @author 你的名字 * @date 2025-01-01 * @version v1.0 * @copyright 某某公司 */三、函数注释
所有对外暴露的函数（头文件中）必须注释。
/** * @brief 函数简要功能（一句话） * * 详细描述函数功能、实现逻辑、使用方法、注意事项 * 可以写多行，支持换行。 * * @param param1 输入参数1说明 * @param param2 输入参数2说明 * @return 返回值说明（无返回值写 void） * @retval 0 成功 * @retval 负数 失败（-1：参数错误 -2：超时） * @see 相关函数名 * @note 注意：调用前必须初始化XXX * @warning 禁止在中断中调用 */int demo_function(int param1, char* param2);四、结构体 / 枚举 / 联合体注释
1. 结构体（struct）
/** * @brief 传感器数据结构体 */typedefstruct { float temperature; /**< 温度值，单位℃ */ int humidity; /**< 湿度值，单位%RH */ unsigned int time; /**< 时间戳 */} SensorData_t;2. 枚举（enum）
/** * @brief 函数执行状态枚举 */typedefenum { STATUS_OK = 0, /**< 执行成功 */ STATUS_ERR_PARAM, /**< 参数错误 */ STATUS_ERR_TIMEOUT /**< 执行超时 */} Status_t;3. 宏定义
/** @brief 串口波特率默认值 */#define UART_BAUDRATE 115200/** * @brief 计算最大值 * @param a 数值1 * @param b 数值2 * @return 较大值 */#define MAX(a,b) ((a)>(b)?(a):(b))五、变量/全局变量注释
/** 全局系统时钟（ms）*/unsigned int sys_tick;/** 传感器采集使能标志 */static bool sensor_enable = false;六、分组注释（模块化管理）
用于把多个函数 / 结构体分成一组，文档更清晰。
/** * @defgroup GPIO_DRIVER GPIO驱动模块 * @brief 控制GPIO输入输出 * @{ *//** @brief 初始化GPIO */void GPIO_Init(void);/** @brief 设置GPIO输出电平 */void GPIO_SetPin(int pin, int level);/** @} */ // 结束分组生成文档后会显示为：GPIO_DRIVER 模块，包含两个函数。
七、最常用 Doxygen 标签速查表
doxygen生成文档的方法
1 生成方法
# 生成配置文件 Doxyfile。doxygen -g Doxyfile# 修改配置文件# 生成html文档doxygen Doxyfile# PDF文档cd docs/latexmake# 查看html和pdf文档xdg-open docs/html/index.htmlxdg-open refman.pdf# 使用其他方法生成pdf文档， 需先安装工具wkhtmltopdfwkhtmltopdf docs/html/index.html docs/项目文档.pdf2 可直接使用的doxyfile配置文件
在项目根目录新建文件 Doxyfile，复制以下内容直接可用（支持 UTF-8 中文、递归扫描 C 文件、生成 HTML + 可配置 PDF）
# ==============================================# Doxygen 配置文件 适配Linux C语言项目# Doxyfile 中文 PDF 完美版（Linux C项目专用）# 解决 LaTeX 中文报错：Unicode character not set up for use with LaTeX# ==============================================DOXYFILE_ENCODING = UTF-8PROJECT_NAME = "C Language Project"PROJECT_NUMBER = V1.0PROJECT_BRIEF = "Linux C 项目接口文档"# 输出路径OUTPUT_DIRECTORY = docsCREATE_SUBDIRS = YES# 源码路径配置INPUT = .INPUT_ENCODING = UTF-8RECURSIVE = YESFILE_PATHS_ENCODING = UTF-8# 针对C语言优化OPTIMIZE_OUTPUT_FOR_C = YESJAVADOC_AUTOBRIEF = YES# 提取全部函数、静态、全局、结构体EXTRACT_ALL = YESEXTRACT_PRIVATE = YESEXTRACT_STATIC = YESEXTRACT_LOCAL_METHODS = YESEXTRACT_LOCAL_CLASSES = YES# 图表支持(graphviz)HAVE_DOT = YESDOT_PATH = /usr/binCALL_GRAPH = YESCALLER_GRAPH = YESGRAPHICAL_HIERARCHY = YESDOT_CHARSET = UTF-8# 开启HTMLGENERATE_HTML = YESHTML_OUTPUT = htmlHTML_INDEX_NUM_ENTRIES = 100# ==================== 下面的配置二选一 ====================# 开启LaTeX生成PDF#GENERATE_LATEX = YES#LATEX_OUTPUT = latex#USE_PDFLATEX = YES#LATEX_CMD_NAME = pdflatex#MAKEINDEX_CMD_NAME = makeindex# ==================== 中文 PDF 核心配置 ====================GENERATE_LATEX = YESLATEX_OUTPUT = latexUSE_PDFLATEX = NOLATEX_CMD_NAME = xelatexPDF_LATEX_CMD = xelatexLATEX_EXTRA_PACKAGES = {ctex, fontspec, geometry}EXTRACT_PACKAGE_STYLE = YES# ============================================================# 中文兼容关键配置PDF_HYPERLINKS = YES3 一键整合操作命令脚本
新建 build_docs.sh
#!/bin/bashset -eecho "=============================="echo "1. 重新扫描源码并生成HTML文档"echo "=============================="doxygen Doxyfileecho "=============================="echo "2. 编译PDF文档 refman.pdf"echo "=============================="cd docs/latexmake cleanmakecd ../..echo "=============================="echo "✅ 文档更新完成"echo "📄 HTML: docs/html/index.html"echo "📑 PDF: docs/latex/refman.pdf"echo "=============================="其他待解决问题
• 如何在生成的文档中添加搜索功能 • 如何在生成的文档中添加自定义页面 • 如何在文档中添加目录 • 如何在文档中添加图标 • 如何在文档中添加超链接
