Doxygen中分离brief和detail区域的图片显示技巧

概述

在使用Doxygen生成文档时，开发者经常需要控制图片在不同区域的显示方式。本文将详细介绍如何在Doxygen的brief(简要说明)和detail(详细说明)区域分别控制图片的显示，实现图片在不同区域的独立展示。

核心原理

Doxygen文档注释中的内容会被自动划分为brief和detail两个部分。默认情况下，第一段内容被视为brief部分，之后的内容则属于detail部分。通过在brief内容后添加一个空行，可以明确分隔这两个区域。

实现方法

1. 基本结构：在注释中首先编写brief内容，然后添加一个空行，接着编写detail内容

2. 自定义图片标签：可以创建类似\dotimg的自定义标签来控制图片显示

   • 该标签可以接受多个参数，如图片路径和关联的引用
   • 通过后处理脚本解析这些标签并生成相应的HTML内容

3. 区域控制：

   • 将\dotimg标签放在brief部分，图片将只出现在brief区域
   • 将标签放在detail部分(空行之后)，图片将只出现在detail区域
   • 通过在两个区域都放置标签，可以实现图片在两个区域的独立显示

实际应用示例

/**
 * @brief 这是brief部分的内容
 * \dotimg{picture.png}{datatypes}{datatypes_unsigned}{datatypes_signed}
 *
 * 这是detail部分的内容
 * \dotimg{another.png}{other_ref1}{other_ref2}
 */

后处理技术

1. 使用Python脚本解析生成的HTML文件
2. 通过正则表达式匹配自定义标签
3. 将标签参数转换为实际的图片映射和链接
4. 生成支持区域点击的图片地图

注意事项

1. 确保在brief和detail部分之间有且仅有一个空行
2. 自定义标签的处理需要配合后处理脚本实现
3. 此方法在Doxygen 1.10.0版本测试通过，其他版本可能需要调整

总结

通过合理利用Doxygen的区域划分机制和自定义标签，开发者可以精确控制图片在不同文档区域的显示方式。这种方法不仅适用于图片，也可以扩展到其他需要区域化控制的内容展示场景。