C# 文档注释的 XML 标记

以下是 C# XML 文档注释的完整类型指南，包含 20+ 个核心标签的使用说明与实战技巧：

一、核心标记（必掌握）

<summary>
用途：描述成员的核心功能
最佳实践：限制在 1-3 句，保持简洁

/// <summary>
/// 验证用户身份凭证的有效性
/// </summary>
public bool ValidateCredentials(string username, string password)

<param>
用途：描述方法参数
扩展属性：name 指定参数名称

/// <param name="retryCount">
/// 最大重试次数（范围：1-5，建议值 3）
/// </param>

<returns>
用途：描述返回值内容及约定

/// <returns>
/// JSON 格式的响应对象，包含 status 和 data 字段
/// </returns>

<exception>
用途：记录可能抛出的异常
类型绑定：使用 cref 指向具体异常类

/// <exception cref="ArgumentNullException">
/// 当输入参数为 null 时抛出
/// </exception>

二、扩展标记（进阶必备）

<remarks>
用途：提供补充说明，可包含多段落

/// <remarks>
/// <para>实现细节：</para>
/// 使用 SHA-256 哈希算法进行加密处理，
/// 每个会话都会生成新的盐值。
/// </remarks>

<example>
用途：展示使用方法
嵌套技巧：配合 <code> 展示示例

/// <example>
/// <code>
/// var util = new CryptoHelper();
/// string hash = util.GenerateHash("secret");
/// </code>
/// </example>

<typeparam>
用途：描述泛型类型参数

/// <typeparam name="T">
/// 必须实现 IComparable 接口的类型
/// </typeparam>
public class SortedList<T> where T : IComparable

<see>
用途：创建交叉引用链接
两种形式：cref 引用类型，href 外部链接

/// <see cref="System.IO.FileStream"/>
/// <see href="https://docs.microsoft.com"/>

三、架构级标记（模块化开发）

<permission>
用途：声明所需权限

/// <permission cref="System.Security.Permissions.FileIOPermission">
/// 需要文件读写权限
/// </permission>

<inheritdoc />
用途：继承基类/接口的文档

/// <inheritdoc />
public override void Execute()

四、复杂场景处理

代码结构优化标记：

/// <code>
/// public class Demo {
///     void Method(){ /*...*/ }
/// }
/// </code>

列表功能标记：

/// <list type="bullet">
/// <item>首次启动初始化配置</item>
/// <item>处理事件订阅</item>
/// <item>启动后台服务</item>
/// </list>

警告提示标记：

/// <note type="caution">
/// 非线程安全方法，需在同步上下文中使用
/// </note>

五、文档生成增强器

<include> 外部引用：

/// <include file='ExternalDocs.xml' path='Docs/Members[@name="Calculator"]/*' />

图像嵌入：

/// <img src="diagrams/class-structure.png" alt="类关系图"/>

六、实战技巧

使用 GhostDoc 扩展自动生成注释框架
通过注释生成 OpenAPI 规范：

/// <response code="200">操作成功返回数据</response>
/// <response code="404">资源不存在</response>

在 CI/CD 中添加文档校验：

dotnet build /p:WarningsAsErrors=CS1591

七、完整结构示例

/// <summary>
/// 订单金额计算器
/// </summary>
/// <remarks>
/// 支持多种货币换算，汇率实时从外部API获取
/// <para>更新频率：每小时同步一次</para>
/// </remarks>
/// <typeparam name="TCurrency">货币代码枚举类型</typeparam>
public class PriceCalculator<TCurrency> where TCurrency : Enum
{
    /// <summary>
    /// 计算含税总金额
    /// </summary>
    /// <param name="basePrice">不含税价格（需大于 0）</param>
    /// <param name="taxRate">税率（0.0 - 1.0 之间）</param>
    /// <returns>包含两位小数的金额字符串</returns>
    /// <exception cref="ArgumentException">税率超过范围时抛出</exception>
    /// <example>
    /// <code>
    /// var calc = new PriceCalculator<Currency>();
    /// string total = calc.CalculateTotal(100.0m, 0.1);
    /// </code>
    /// </example>
    public string CalculateTotal(decimal basePrice, double taxRate)
    {
        // 实现代码...
    }
}

将 XML 注释集成到开发流程中，可以：