Doxygen无法生成文件描述问题求助

针对你遇到的.ctl文件（映射为C++）的@brief注释无法在HTML文件列表中显示的问题，给你几个可行的排查和解决步骤：

1. 添加.ctl到FILE_PATTERNS配置
   默认情况下Doxygen只会处理预设后缀的文件，即便你设置了EXTENSION_MAPPING，也需要显式把.ctl加入FILE_PATTERNS，否则文件可能未被完整解析。在配置文件中添加：

   FILE_PATTERNS          = *.ctl *.cpp *.h
   

2. 修正@file指令的参数
   你用的$relPath不是Doxygen的内置变量，Doxygen无法识别这个占位符，会导致文件关联失败，进而无法展示brief。可以直接填写文件的实际名称，或者留空让Doxygen自动识别：

   /**
    * @file
    * @brief Description test
    * @copyright $copyright
    * @author dcasado
    */
   

3. 显式开启EXTRACT_FILES
   尽管你设置了EXTRACT_ALL=YES，部分Doxygen版本仍需要显式开启EXTRACT_FILES=YES才能确保文件级注释被提取到文件列表中：

   EXTRACT_FILES          = YES
   

4. 统一文件注释格式
   确保注释块的指令顺序和格式规范，@file作为第一个指令，@brief紧跟其后，每行开头的*保持一致（避免缩进混乱）：

   /**
    * @file your_file.ctl
    * @brief Description test
    * @copyright $copyright
    * @author dcasado
    */
   

最后，记得清空输出目录后重新生成文档，避免旧缓存影响结果。

内容的提问来源于stack exchange，提问作者diego