Doxygen with C#

1. 安装 Doxygen

1. 下载 ：访问 Doxygen 官网 https://www.doxygen.nl/download.html 下载并安装最新版本的 Doxygen for Windows。

2. 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

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

1. GUI 工具 (Doxywizard) ： 推荐新手使用。它在开始菜单中名为 Doxywizard。

2. 配置文件 (Doxyfile)： 高级用户通常直接编辑这个文本配置文件。

使用 Doxywizard 的步骤：

1. 指定工作目录：选择你的 C# 项目根目录。

2. 向导 (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 等。

3. 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。

4. 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

---

进阶技巧与常见问题

1. 忽略 #region 和 #endregion ：

   Doxygen 有时会错误地将 #region 解释为无效命令。一个常见的解决方案是创建一个简单的过滤器程序（如 Python 脚本），在 Doxygen 处理前将 #region 替换为 //#region。然后在 Expert 设置中配置 INPUT_FILTER 指向这个脚本。

2. 中文支持：

   • 在 Expert 设置中，找到 Project > OUTPUT_LANGUAGE 并设置为 Chinese。

   • 确保你的 Doxyfile 和源代码文件是 UTF-8 编码。

3. 与 CI/CD 集成 ：

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

4. 美化输出 ：

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