Doxygen/GraphViz生成C#协作图时无法识别集合类关联

我有一个C#项目，使用Doxygen v1.12.0和GraphViz dot v12.0.0生成协作图。当类使用List<T>（例如public List<Item> Items = new List<Item>();）时，图中不会生成当前类与Item类的关联；但使用数组（例如Item[] Items = new Item[10];）时，关联能正常显示。

请问是否有方法让Doxygen识别C#集合类？若没有，有没有不替换为数组的替代方案（比如把所有List<?>转换为?[]的预处理器）？

补充配置与环境 #

• Doxygen版本：v1.12.0
• Graphviz版本：dot v12.0.0
• Doxyfile关键配置：

OUTPUT_DIRECTORY       = ./Docs/
OPTIMIZE_OUTPUT_JAVA   = YES
EXTRACT_ALL            = YES
EXTRACT_PRIVATE        = YES
EXTRACT_PACKAGE        = YES
EXTRACT_LOCAL_CLASSES  = NO
HIDE_UNDOC_CLASSES     = YES
INPUT                  = ./Assets/Scripts/
RECURSIVE              = YES
HTML_EXTRA_STYLESHEET  = ./Docs/doxygen-awesome-css/doxygen-awesome.css
HTML_COLORSTYLE        = LIGHT
GENERATE_TREEVIEW      = YES
GENERATE_LATEX         = NO
HAVE_DOT               = YES
UML_LOOK               = YES
TEMPLATE_RELATIONS     = YES
CALL_GRAPH             = YES
CALLER_GRAPH           = YES
DIR_GRAPH_MAX_DEPTH    = 25
DOT_IMAGE_FORMAT       = svg
DOT_GRAPH_MAX_NODES    = 100

示例代码 #

public class ClassB { 
}
public class ListA {
    List<ClassB> myList = new List<ClassB>();
}
public class ArrA {
    ClassB[] myArr = new ClassB[10];
}

（注：示例中ArrA与ClassB的关联会被绘制，但ListA与ClassB的关联不会）

解决方案 #

方法一：调整Doxygen核心配置 #

Doxygen默认对C#泛型集合的关联识别存在局限，可通过修改配置改善：

• 将OPTIMIZE_OUTPUT_JAVA改为NO：该配置针对Java优化，开启后会干扰C#泛型解析
• 确保TEMPLATE_RELATIONS保持YES：此选项允许Doxygen跟踪模板类型的依赖关系
• 添加ENABLE_PREPROCESSING = YES和MACRO_EXPANSION = YES，为后续宏处理做准备

方法二：用Doxygen宏别名映射 #

在Doxyfile中添加宏定义，让Doxygen在解析阶段把List<T>识别为数组结构，不修改实际代码：

PREDEFINED += List<T>=T[]

如果需要保留文档中List<T>的原显示名称，可使用更精细的宏配置：

PREDEFINED += List@<T@>=List<T>
EXPAND_ONLY_PREDEF = YES

这种方式既能让Doxygen生成关联图，又不影响文档里的类型展示。

方法三：手动添加注释标记建立关联 #

不想修改全局配置的话，可在代码中通过Doxygen注释强制声明关联：

public class ListA {
    /// <summary>
    /// 列表元素为@ref ClassB
    /// </summary>
    List<ClassB> myList = new List<ClassB>();
}

或者用@link标记更直观地关联：

public class ListA {
    /// <summary>
    /// 存储@link ClassB ClassB类型@endlink的元素
    /// </summary>
    List<ClassB> myList = new List<ClassB>();
}

这种方式精准可控，但需要逐个修改目标代码。

方法四：自定义预处理脚本临时转换 #

如果上述方法都不满足，可写脚本在Doxygen扫描前临时修改代码，生成文档后恢复：
以下是Python脚本示例：

import os
import fileinput

def replace_list_with_array(path):
    for root, dirs, files in os.walk(path):
        for file in files:
            if file.endswith(".cs"):
                file_path = os.path.join(root, file)
                with fileinput.FileInput(file_path, inplace=True, backup='.bak') as f:
                    for line in f:
                        print(line.replace('List<', '').replace('>', '[]'), end='')

# 处理目标代码目录
replace_list_with_array("./Assets/Scripts/")
# 运行Doxygen生成文档
os.system("doxygen Doxyfile")

def restore_backup_files(path):
    for root, dirs, files in os.walk(path):
        for file in files:
            if file.endswith(".cs.bak"):
                bak_path = os.path.join(root, file)
                original_path = bak_path[:-4]
                os.replace(bak_path, original_path)

# 恢复原代码文件
restore_backup_files("./Assets/Scripts/")

脚本会自动完成临时替换、生成文档、恢复原文件的流程，不影响实际开发代码。

内容的提问来源于stack exchange，提问作者Sam Van Battel