Doxygen with C# - 技术栈

1. 安装 Doxygen

下载：访问 Doxygen 官网 https://www.doxygen.nl/download.html 下载并安装最新版本的 Doxygen for Windows。
Graphviz (可选但推荐) ：为了生成包含类图、协作图等更直观的图表，请同时下载并安装 Graphviz (https://graphviz.org/download/)。安装后，记下它的安装路径（例如 C:\Program Files\Graphviz\bin）。

2. 准备你的 C# 项目代码

Doxygen 通过读取源代码中的特殊注释来工作。C# 的标准文档注释使用三斜杠 ///，这与 Doxygen 完美兼容。

C# 注释示例：

复制代码

/// <summary>
/// 这是一个表示人的类。
/// 它包含了人的基本属性和方法。
/// (Doxygen 支持 XML 注释和 Markdown)
/// </summary>
public class Person
{
    /// <summary>
    /// 获取或设置人的姓名。
    /// </summary>
    /// <value>字符串类型的姓名。</value>
    public string Name { get; set; }

    /// <summary>
    /// 人的年龄（岁）。
    /// </summary>
    private int _age;

    /// <summary>
    /// 根据姓名和年龄初始化一个新的 <see cref="Person"/> 实例。
    /// </summary>
    /// <param name="name">这个人的姓名。</param>
    /// <param name="age">这个人的年龄。</param>
    /// <exception cref="ArgumentException">当年龄为负数时抛出。</exception>
    public Person(string name, int age)
    {
        Name = name;
        if (age < 0)
        {
            throw new ArgumentException("年龄不能为负数。", nameof(age));
        }
        _age = age;
    }

    /// <summary>
    /// 让人进行自我介绍。
    /// </summary>
    /// <returns>包含姓名和年龄的自我介绍字符串。</returns>
    public string Introduce()
    {
        return $"你好，我叫 {Name}，今年 {_age} 岁。";
    }
}

关键注释标签：

<summary>：对类、方法、属性等的简要说明。
<param name="name">：描述方法的参数。
<returns>：描述方法的返回值。
<value>：描述属性的值。
<exception>：描述方法可能抛出的异常。
<see cref="MemberName"/>：创建到其他代码元素（如类、方法）的交叉引用。
<code> / <c>：插入代码片段或行内代码。

你也可以使用 JavaDoc 风格 (/** ... */)，但 /// 是 C# 社区的标准。

3. 配置 Doxygen

配置是核心步骤。你有两种方式：

GUI 工具 (Doxywizard) ：推荐新手使用。它在开始菜单中名为 Doxywizard。
配置文件 (Doxyfile)：高级用户通常直接编辑这个文本配置文件。

使用 Doxywizard 的步骤：

指定工作目录：选择你的 C# 项目根目录。
向导 (Wizard) 标签页：
- Project 页：
  - Project name：你的项目名称（如 "MyCSharpApp"）。
  - Source code directory：浏览选择你的源代码文件夹。
  - Destination directory ：选择生成的文档的输出文件夹（如 ./docs）。不要选源码目录。
- Mode 页：选择 All entities 和 Optimize for C++ or Java output。虽然我们用的是 C#，但这个模式效果很好。
- Output 页：选择输出格式。HTML 是必选的，LaTeX 可选。
- Diagrams 页：强烈推荐！
  - 勾选 Use dot tool from the Graphviz package。
  - 在 Dot path 中填写 Graphviz 的 bin 目录路径（例如 C:\Program Files\Graphviz\bin）。
  - 勾选你想要的图表，如 Class diagrams, Collaboration diagrams 等。
Expert (专家) 标签页 - 关键 C# 相关设置：
- Project > EXTENSION_MAPPING ：确保已有 cs=CSharp。这告诉 Doxygen 把 .cs 文件当作 C# 代码处理。
- Project > OUTPUT_LANGUAGE ：保持 English 即可，输出语言主要由你的注释决定。
- Build > EXTRACT_ALL ：设置为 YES。这将为所有实体（即使没有注释的）生成文档，方便初期检查。
- Build > EXTRACT_PRIVATE ：设置为 YES 如果你想为 private 成员也生成文档。
- Build > EXTRACT_STATIC ：设置为 YES。
- Input > FILTER_PATTERNS ：可以设置为 *.cs=dotnet-csharp-filter.exe（高级用法 ，用于预处理#region等，通常可不设）。
- Input > FILE_PATTERNS ：确保列表中包含 *.cs。
Run (运行) 标签页 ：点击 Run doxygen 按钮开始生成文档。完成后点击 Show HTML Output 查看结果。

4. 生成文档

在 Doxywizard 中：点击 "Run doxygen" 然后 "Show HTML Output"。
在 命令行 中：如果你有 Doxyfile，可以在项目根目录打开命令行/终端，直接输入：

doxygen Doxyfile

5. 查看结果

生成完成后，打开输出目录（例如 ./docs/html/）下的 index.html 文件。你就看到了一个完整的、类似 MSDN 的 API 文档网站，包含了所有的类、命名空间、方法列表和详细的说明。

https://www.doxygen.nl/manual/screenshots/html_8h.png

进阶技巧与常见问题

忽略 #region 和 #endregion ：

Doxygen 有时会错误地将 #region 解释为无效命令。一个常见的解决方案是创建一个简单的过滤器程序（如 Python 脚本），在 Doxygen 处理前将 #region 替换为 //#region。然后在 Expert 设置中配置 INPUT_FILTER 指向这个脚本。
中文支持：
- 在 Expert 设置中，找到 Project > OUTPUT_LANGUAGE 并设置为 Chinese。
- 确保你的 Doxyfile 和源代码文件是 UTF-8 编码。
与 CI/CD 集成 ：

你可以将 Doxyfile 纳入版本控制（如 Git）。在你的持续集成/持续部署管道（如 GitHub Actions, Azure DevOps）中，添加一个步骤来安装 Doxygen 和 Graphviz，然后执行 doxygen Doxyfile 命令，自动将生成的文档部署到服务器或 GitHub Pages。
美化输出 ：

Doxygen 允许你完全自定义 HTML、CSS 和 LaTeX 输出的外观。你可以修改默认的样式表或使用第三方主题。