Doxygen 1.8.13下C++函数文档追加而非替换的方案问询

需求背景 #

当前使用Doxygen 1.8.13，需生成满足ASPICE要求的外部/内部文档，具体要求：

• 代码包含抽象基类（接口类）及多个实现类
• 已在interface.h中为抽象基类编写调用契约作为外部文档
• 希望在implementation.cpp的函数上方追加对外可见的实现类接口相关功能说明
• 需在独立文件implementation.dox中添加仅QA和审计人员关注的详细设计、实现信息及GUID追溯内容，通过两个Doxyfile控制是否包含该文件

遇到的问题 #

• 实现类会自动继承基类的简要和详细文档（但不包含参数），添加新内容会直接覆盖原有继承的文档，只能用@copydoc <base method>复制原信息后追加
• 在implementation.dox中使用@fn <method>会覆盖原有文档，且无法通过@copydoc复制实现类的已有信息

可行实现方案 #

Doxygen 1.8.13 原生没有类似@appendto的直接追加命令，但可以通过以下两种方式实现需求，无需脚本或怪异预处理：

1. 实现类文档追加：@copydoc+自定义段落 #

在implementation.cpp的实现函数注释中，先用@copydoc完整复制基类的调用契约文档，再追加实现类特有的对外说明。示例：

/**
 * @copydoc InterfaceClass::doSomething()
 * 
 * 本实现类采用XX算法优化处理效率，支持XX边界场景的兼容处理
 */
void ImplementationClass::doSomething(int param) {
    // 实现代码
}

这种方式既保留了基类的完整契约（包括参数说明），又添加了实现类的专属信息，不会覆盖原有继承内容。

2. 内部文档分离：@internal标签+Doxyfile配置 #

方案A：无需独立.dox文件

在implementation.cpp的函数注释末尾添加@internal块，将内部敏感的详细设计、GUID追溯内容放入其中：

/**
 * @copydoc InterfaceClass::doSomething()
 * 
 * 本实现类采用XX算法优化处理效率，支持XX边界场景的兼容处理
 * 
 * @internal
 * 详细设计：采用XX状态机实现，对应需求GUID: XXX-XXXX-XXXX
 * 实现细节：处理流程为XXX→XXX→XXX，异常分支覆盖XX、XX两种场景
 */
void ImplementationClass::doSomething(int param) {
    // 实现代码
}

通过两个Doxyfile控制显示逻辑：

• 外部文档Doxyfile：设置INTERNAL_DOCS = NO，@internal块内容会被隐藏
• 内部文档Doxyfile：设置INTERNAL_DOCS = YES，将显示所有@internal标记的详细内容

方案B：使用独立.dox文件

如果必须用implementation.dox存放内部内容，可在文件中用@relates关联目标实现类，同时配合@internal标签：

/**
 * @relates ImplementationClass
 * @internal
 * 详细设计：ImplementationClass::doSomething()采用XX状态机实现，对应需求GUID: XXX-XXXX-XXXX
 * 实现细节：处理流程为XXX→XXX→XXX，异常分支覆盖XX、XX两种场景
 */

再通过Doxyfile的INPUT配置控制文件是否被包含：

• 外部文档：INPUT中排除implementation.dox
• 内部文档：INPUT中添加implementation.dox

关键注意事项 #

• Doxygen 1.8.13中，@copydoc可以完整复制基类的所有文档元素（包括@param、@return等标签），前提是基类文档规范编写
• 禁止用@fn重复声明方法，它会直接覆盖原有文档，改用@relates或@internal来关联补充内容

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