<p>Doxygen默认不解析无注释代码，但启用EXTRACT_ALL=YES可强制提取符号结构（如签名、权限、继承关系），而参数含义等语义信息仍为空；仅///和//开头的注释块被识别，普通//或/ /被忽略。</p>
Doxygen 能不能直接解析没加注释的 C++ 代码
不能，但可以强制提取符号结构。默认情况下，Doxygen 只处理带特定标记（如 /// 或 /**）的注释块；没写注释的函数、类、变量会被跳过。若想让文档覆盖所有符号（哪怕没注释），必须在 Doxyfile 中设 EXTRACT_ALL = YES。
注意：EXTRACT_ALL 不等于“自动生成语义说明”，它只把签名、访问权限、继承关系等基本信息拉出来，参数名、返回值含义、行为逻辑仍为空。调试阶段可开，上线前建议关掉，否则文档里一堆“Undocumented function”反而干扰阅读。
-
EXTRACT_PRIVATE = YES才能显示private成员（默认不显示） -
EXTRACT_STATIC = YES才会包含static函数和变量 -
HIDE_UNDOC_MEMBERS = YES和EXTRACT_ALL冲突——开了后者，前者就失效
哪些注释写法会被 Doxygen 正确识别
只有两种开头被当作文档块：///（单行或连续多行）和 /**（C 风格块注释）。普通 // 或 /* */ 完全忽略。
推荐用 /// 写函数级注释，简洁不易出错；用 /** */ 写类/命名空间级长说明。关键标签必须紧贴参数或返回值，大小写敏感，比如 @param 不能写成 @Param。
立即学习“C++免费学习笔记（深入）”；
- 函数前加
/// @brief 描述+/// @param name 说明+/// @return 说明 - 类前用
/** @brief ... @details ... */区分摘要与细节 - 头文件顶部加
/** @mainpage */定义首页内容，否则首页只是空导航栏 - 避免在注释里混用 Markdown 表格或复杂 HTML——
Doxygen渲染能力有限，易崩或错位
INPUT 和 FILE_PATTERNS 配置容易漏掉什么
INPUT 指定源码路径，但默认只扫 *.c *.h，C++ 项目必须显式加 *.cpp *.hpp *.cc *.cxx 到 FILE_PATTERNS，否则 .cpp 里的 @param 注释根本不会被读取。
常见疏忽：INPUT 写成 src/ 却忘了设 RECURSIVE = YES，结果子目录全被跳过；或者把 include/ 和 src/ 分开列在 INPUT 里，但没确认两者路径是否真实存在（拼写错误、大小写不符在 macOS/Linux 下直接失效）。
-
INPUT = include/ src/ tests/—— 多路径用空格分隔，不是逗号 -
FILE_PATTERNS = *.h *.hpp *.cpp *.cc *.cxx *.tpp—— 模板实现文件.tpp常被遗漏 -
EXCLUDE_PATTERNS = */test_* */mock_*—— 排除测试/模拟代码，避免污染 API 文档
生成 HTML 后打开 index.html 为啥一片空白或报错
最常见原因是输出路径权限问题或 GENERATE_HTML = YES 没生效。运行 doxygen Doxyfile 后检查终端是否有类似 error: cannot open file 'html/index.html' 的提示——这说明 OUTPUT_DIRECTORY 目录不可写，或父路径不存在。
另一个高频坑：本地直接双击 html/index.html 打开，浏览器因安全策略禁用 file:// 协议下的 JS 交互（搜索、折叠菜单、图表渲染全挂），导致页面看起来“空”。必须用 HTTP 服务启动，例如：python3 -m http.server -d html 8000，再访问 http://localhost:8000。
- 确认
HTML_OUTPUT = html（不是docs/html等嵌套路径） - 检查
html/目录下是否有index.html和tabs.css等基础文件，缺失说明生成中途失败 - 如果用了
doxygen-awesome-css等主题，确保HTML_EXTRA_STYLESHEET路径正确且 CSS 文件存在
模板特化、constexpr if、模块（import）这些现代 C++ 构造，Doxygen 解析依然吃力。别指望它自动推导 SFINAE 条件或展开概念约束——注释得手动补全，否则文档里只剩个空壳签名。
