Doxygen代码段#注释不显示及路径含*/解析异常求助

一、让bash代码段内的#注释正常显示 #

1. 明确指定代码语言
   确保使用@code{bash}或@code{.sh}标记代码段，让Doxygen准确识别bash语法，避免把#注释误判为文档注释。正确写法：

   @code{.sh}
   # 这条bash注释会正常显示
   echo "执行脚本"
   # 另一条注释也能显示
   @endcode
   

2. 配置Doxygen的语言映射
   在Doxygen配置文件（Doxyfile）中添加或修改EXTENSION_MAPPING，确保sh文件被映射为bash语言：

   EXTENSION_MAPPING = sh=bash
   

   这能让Doxygen对bash代码的语法解析更准确，包括识别#注释。

3. 用@verbatim强制原样输出
   如果上述方法无效，改用@verbatim替代@code，它会完全保留代码的原始格式，不做任何语法解析：

   @verbatim
   # 不管什么注释都能原样显示
   ls /path/with/*/special/chars
   @endverbatim
   

二、正确书写含*/、/*/的路径避免解析异常 #

1. 普通文档文本中转义特殊字符
   在非代码段的文档描述里，把*/转义为*\*，/*/转义为/\*/，防止Doxygen把它们误判为注释结束标记：

   请访问路径 `/usr/local/\*/bin`，或配置目录 `/opt/\*/lib/\*/`
   

2. 代码段内直接书写无需转义
   只要代码段被@code{.sh}或@verbatim正确包裹，路径里的*/或/*/可以直接写，Doxygen会按代码内容处理，不会解析为文档注释：

   @code{.sh}
   # 代码里的特殊路径直接写就行
   cp /source/*/file /dest/\*/
   @endcode
   

3. 检查文档注释的嵌套问题
   避免在普通文档注释中出现未转义的*/，比如不要写/* 参考路径 */usr/local/*/bin，这种写法会让Doxygen提前结束注释，导致后续内容解析混乱，必须转义路径中的特殊字符。

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