Doxygen 1.9.8中如何避免为特定文件生成页面但保留其文档内容？

这个场景我太熟悉了——开着EXTRACT_ALL=YES省了手动给每个头文件加\file的麻烦，结果却让那些只用来定义组/文档的.md/.txt文件生成一堆空页面，不仅乱了Files列表，还在搜索结果里添乱，关键还不能直接排除这些文件，因为里面的@defgroup这类定义是文档的核心部分。针对Doxygen 1.9.8，我有几个实用的解决方案，你可以按需选择：

1. 批量给头文件添加@file命令（最推荐，一劳永逸） #

你提到手动给所有头文件加\file太麻烦，但用脚本批量处理其实只需要几分钟，这是最彻底的解决方案：

• 用find+sed组合脚本，自动给所有.h/.hpp文件的开头添加@file注释（还会跳过已经有@file的文件，避免重复）：

  # 遍历当前目录及子目录下的所有头文件，批量添加@file注释
  find . -type f \( -name "*.h" -o -name "*.hpp" \) | while read -r header_file; do
    # 检查文件开头是否已经包含@file标记
    if ! grep -q "^[/*]*@file" "$header_file"; then
      # 在文件第一行插入@file注释块
      sed -i '1s/^/\/*\* @file *\//\n/' "$header_file"
    fi
  done
  

• 脚本执行完后，修改你的Doxyfile：把EXTRACT_ALL=YES改成EXTRACT_ALL=NO，保留SHOW_FILE=YES。
• 效果：只有加了@file的头文件会生成文件页面，而.md/.txt文档文件因为没有@file标记，不会生成空页面，但里面的@defgroup等命令会被Doxygen正常处理，完全不影响文档结构。

2. 给文档文件添加“占位”@file标记（无需改EXTRACT_ALL的折中方案） #

如果你暂时不想调整EXTRACT_ALL的设置，可以给那些.txt/.md文档文件加一个简单的占位@file注释，这样生成的文件页面就不是空的，还能明确说明文件的作用：

/**
@file
@brief 该文件用于定义文档分组，不提供独立的文件级细节
*/

/**
* Feature Title
*
* @defgroup FeatureGroupName Feature
*
* Here is a description of what does the feature!
*/

• 这样处理后，这些文件的页面不会是空的，搜索结果里的条目也有意义；如果还是不想让它们出现在Files列表里，可以结合修改Layout.xml隐藏指定文件，但这个操作相对繁琐，不如第一种方法彻底。

3. 扩展InputFilter脚本过滤文件页面生成（进阶技巧） #

既然你已经在使用INPUT_FILTER的sed脚本，可以扩展它让Doxygen忽略这些文档文件的页面生成，但保留里面的命令：

• 修改你的InputFilter.sed，添加针对.txt/.md文件的处理逻辑，给它们添加@cond标记隐藏文件页面内容：

  # 对.txt和.md文件，在开头添加隐藏标记，结尾闭合
  /\.txt$/,/\.md$/{
    1i\
  /** @cond HIDE_FILE_PAGE */\
  @file
    $a\
  /** @endcond */
  }
  

• 注意：这个方法需要调试sed脚本，确保不会破坏原有的注释结构，而且Doxygen还是会生成文件页面，只是内容被隐藏了，属于临时的折中方案，不如第一种方法直接。

总的来说，最推荐第一种批量处理头文件的方案，一劳永逸解决问题，后续维护也更清晰。

备注：内容来源于stack exchange，提问作者O.Marcou