Doxygen不会自动补全API文档，必须严格按规范书写结构化注释并正确配置Doxyfile；注释须紧贴声明、使用UTF-8无BOM编码、标注完整@param/@return等标签，否则生成内容缺失。
Doxygen 不会“自动”生成可用的 API 文档——它只忠实提取你明确写进注释里的结构化信息；没写 @param，HTML 里就不会有参数表；类成员注释没贴在 .h 文件的声明行上方，就根本不会出现在索引里。
注释必须紧贴声明，且位置不能错
Doxygen 默认只扫描函数/类/变量声明正上方、无空行隔开的注释块。哪怕中间插了一行宏、一个 #ifdef 或一个空行，它就会跳过整个符号。
-
///单行注释必须直接顶在声明前一行（例如构造函数前），不能有空行 -
/** */块注释也必须紧贴，推荐用/**<code> 开头（注意星号后紧跟文字），否则可能被识别为普通注释 - 类成员函数若定义在
.cpp文件中，Doxygen 默认不处理——必须把注释写在.h的声明处，而不是.cpp的实现处 - 模板类或函数要加
@tparam，否则生成文档时模板参数名会丢失
Doxyfile 配置不能靠手写，得先 doxygen -g
手动编辑 Doxyfile 极易漏关键项，尤其是编码和路径相关设置。正确做法是：在项目根目录执行 doxygen -g Doxyfile 生成默认配置，再针对性修改以下几项：
-
PROJECT_NAME和OUTPUT_DIRECTORY：避免路径含空格或中文，否则某些平台下生成失败 -
INPUT：只填头文件目录（如./include ./src），别写.，否则可能扫到build/或cmake-build-debug/ -
RECURSIVE = YES：子目录不设这个，就只扫当前层 -
EXTRACT_ALL = NO（推荐）+EXTRACT_STATIC = YES：防止内部工具函数全暴露，同时保留静态成员文档 -
INPUT_ENCODING = UTF-8：中文注释必须设此项，否则解析中断或乱码
生成的 HTML 没参数、没返回值？不是 bug，是你没标
Doxygen 不推导语义，int foo(int x) 不会自动生成 “x: input integer”。所有接口契约都得人工标注，否则文档就是空壳。
C++ Code Review Master
下载
组合式C++代码评审方案，融合静态分析、AI推理、多轮迭代评审和C++专项检查，适用于PR审查、增量代码审查、全项目评审和代码质量评分，触发词包括review cpp、cpp代码评审、C++review、代码审查。
立即学习“C++免费学习笔记（深入）”；
-
@param [in|out|in,out] name description：括号内方向虽可选，但加上后生成的 HTML 参数表会带图标和说明列，可读性提升明显 -
@return后不要只写类型（如@return bool），要写清楚语义（如@return true on success, false if file not found） - 重载函数之间用
@overload关联，否则各版本文档孤立，用户无法对比差异 - C++20
concept目前不被原生支持，得当普通文本写进@brief或注释正文里
中文注释失效或搜索空白？大概率是 BOM 或编码混用
Windows 记事本保存的 .h 文件常带 BOM 或 ANSI 编码，Doxygen 解析时会卡在第一个非 ASCII 字符上，导致注释截断、符号丢失、搜索功能瘫痪。
- 所有源文件必须保存为 UTF-8 without BOM（VS Code / CLion 默认符合；记事本需「另存为」→ 手动选编码）
-
Doxyfile中确认INPUT_ENCODING = UTF-8，且未被其他配置项覆盖 - 如果用了第三方 CSS（如
doxygen-awesome.css），确保其本身也用 UTF-8 编码，否则中文样式会错位
最常被忽略的一点：Doxygen 不校验你写的 @param 名称是否真在函数签名里出现——拼错、大小写不一致、多写少写一个下划线，都会导致该参数在 HTML 中彻底消失，而命令行也不会报错。
