为C#项目编写文档：从A到Z

为什么需要高质量的C#项目文档？

文档是开发者和代码用户之间的桥梁。在C# (.NET)世界中，这座桥梁是通过XML注释和专用工具（DocFX、Sandcastle）构建的。好的文档可以：

• 加快新开发人员熟悉项目的速度
• 减少聊天和工单中的问题数量
• 提高代码质量（在编写文档时，你会不自觉地重构糟糕的方法）
• 自动生成API参考（Visual Studio中的IntelliSense）

在本文中，我们将介绍完整的流程：从项目配置到将文档发布到静态网站。所有示例均使用C# (.NET 8)。

1. XML注释：C#文档的基础

1.1. 如何启用XML文件生成

Visual Studio（或Rider）会在启用相应选项时自动生成包含注释的XML文件，在.csproj中配置：

<PropertyGroup>    <GenerateDocumentationFile>true</GenerateDocumentationFile>    <DocumentationFile>bin\\$(Configuration)\\$(TargetFramework)\\$(AssemblyName).xml</DocumentationFile></PropertyGroup>

构建后，在bin/Debug/net8.0/文件夹中会出现包含注释的XML文件。这个文件是DocFX和Sandcastle的原始素材。

1.2. 主要的XML标签

为C#项目编写文档时，请使用以下标签：

• <summary> — 类、方法、属性的简要描述。
• <param name="..."> — 方法参数的描述。
• <returns> — 返回值的描述。
• <exception cref="..."> — 方法可能抛出的异常。
• <example> — 使用示例。
• <see cref="..."> — 指向其他类型或方法的链接。
• <code> — 描述中的格式化代码。

1.3. 完整注释示例

/// <summary>/// 执行两个数字的安全除法，并进行零值检查。/// </summary>/// <param name="dividend">被除数（分子）。</param>/// <param name="divisor">除数（分母）。不能等于0。</param>/// <returns>以十进制分数形式返回的除法结果。</returns>/// <exception cref="DivideByZeroException">如果divisor等于0，则抛出此异常。</exception>/// <example>/// <code>/// double result = SafeDivider.Divide(10, 3);/// Console.WriteLine(result); // 3.333.../// </code>/// </example>public static double Divide(double dividend, double divisor){    if (divisor == 0)        throw new DivideByZeroException("禁止除以零。");    return dividend / divisor;}

建议：如果项目是内部项目，请用中文编写注释；如果是开放API，请用英文编写。关键是保持统一的风格。

2. 文档生成工具：DocFX vs Sandcastle

2.1. DocFX（推荐）

DocFX 是微软的现代工具，它从XML注释和额外的Markdown文件生成静态网站。它支持C#、VB.NET甚至JavaScript。

安装：

dotnet tool install -g docfx

快速开始：

docfx init -o my-docscd my-docsdocfx builddocfx serve _site

DocFX自动：

• 扫描你的.csproj和.sln文件
• 提取XML注释
• 为每个类、方法、属性创建页面
• 添加导航、搜索和漂亮的主题（默认使用Bootstrap）