C#常用的注释标签

最常用的注释标签清单

标签	说明	示例
<summary>	概要描述	/// <summary>这是一个下载器。</summary>
<remarks>	详细说明或补充备注	/// <remarks>该类线程不安全。</remarks>
<param>	描述方法参数	/// <param name=""url"">下载地址。</param>
<typeparam>	描述泛型类型参数	/// <typeparam name=""T"">结果类型。</typeparam>
<returns>	描述返回值	/// <returns>返回下载的内容。</returns>
<value>	描述属性值	/// <value>当前下载的 URL。</value>
<example>	提供示例代码	/// <example>var d = new Downloader();</example>
<exception>	说明可能抛出的异常	/// <exception cref=""IOException"">文件无法访问。</exception>
<see>	在说明中引用类、方法或成员	/// <see cref=""HttpClient"" />
<seealso>	“另请参阅”引用	/// <seealso cref=""DownloadAsync"" />
<inheritdoc>	继承父类或接口的注释	/// <inheritdoc />
<para>	段落分隔符	<para>第一段</para><para>第二段</para>
<list>	列表展示	见下方示例
<c>	行内代码（小代码块）	/// 调用 <c>DownloadAsync()</c> 方法。
<code>	多行代码块	见下方示例
<paramref>	引用参数名	/// 如果 <paramref name=""url""/> 为空则抛异常。
<typeparamref>	引用泛型类型参数	/// 返回 <typeparamref name=""T""/> 类型对象。
<include>	从外部 XML 文件导入注释	用于大型项目文档集中管理

一个完整的类注释模板

using System;
using System.Collections.Generic;
using System.Threading.Tasks;

namespace DocCommentDemo
{
    /// <summary>
    ///     表示一个用于下载和缓存文件的工具类。
    /// </summary>
    /// <remarks>
    ///     <para>此类封装了 <see cref=""System.Net.Http.HttpClient"" /> 的常用下载逻辑。</para>
    ///     <para>默认情况下，每个实例维护独立缓存，不适合在多个线程中共享。</para>
    /// </remarks>
    /// <example>
    ///     基本用法：
    ///     <code>
    ///     var downloader = new FileDownloader();
    ///     await downloader.DownloadAsync(""https://example.com/file.zip"", ""C:\\temp\\file.zip"");
    ///     </code>
    /// </example>
    /// <seealso cref=""ICacheProvider"" />
    public class FileDownloader
    {
        /// <summary>
        ///     初始化 <see cref=""FileDownloader""/> 类的新实例。
        /// </summary>
        public FileDownloader()
        {
        }

        /// <summary>
        ///     下载指定 URL 的文件并保存到目标路径。
        /// </summary>
        /// <param name=""url"">要下载的文件 URL。</param>
        /// <param name=""destinationPath"">下载文件保存路径。</param>
        /// <typeparam name=""TResult"">下载完成后处理结果的类型。</typeparam>
        /// <returns>一个表示异步下载任务的 <see cref=""Task{TResult}"" />。</returns>
        /// <exception cref=""ArgumentNullException"">
        ///     当 <paramref name=""url""/> 或 <paramref name=""destinationPath""/> 为空时抛出。
        /// </exception>
        /// <exception cref=""InvalidOperationException"">
        ///     当文件下载失败或响应异常时抛出。
        /// </exception>
        /// <example>
        ///     <code>
        ///     var result = await downloader.DownloadAsync&lt;string&gt;(""https://cdn.tailwindcss.com"", ""tailwind.exe"");
        ///     Console.WriteLine(result);
        ///     </code>
        /// </example>
        public async Task<TResult> DownloadAsync<TResult>(string url, string destinationPath)
        {
            // 模拟异步操作
            await Task.Delay(1000);
            return default!;
        }

        /// <summary>
        ///     获取或设置下载进度百分比。
        /// </summary>
        /// <value>
        ///     一个介于 0 到 100 之间的整数，表示当前下载进度。
        /// </value>
        public int Progress { get; private set; }

        /// <summary>
        ///     当前下载器的缓存提供程序。
        /// </summary>
        /// <seealso cref=""ICacheProvider"" />
        public ICacheProvider CacheProvider { get; set; } = new MemoryCacheProvider();

        /// <summary>
        ///     检查文件是否已存在于缓存中。
        /// </summary>
        /// <param name=""url"">文件的下载地址。</param>
        /// <returns>如果文件存在于缓存中，则返回 <c>true</c>；否则返回 <c>false</c>。</returns>
        public bool IsCached(string url)
        {
            return CacheProvider.Contains(url);
        }

        /// <summary>
        ///     获取该类支持的文件类型。
        /// </summary>
        /// <list type=""bullet"">
        ///     <item><description>.zip</description></item>
        ///     <item><description>.exe</description></item>
        ///     <item><description>.tar.gz</description></item>
        /// </list>
        public string[] SupportedFileTypes => new[] { "".zip"", "".exe"", "".tar.gz"" };
    }

    /// <summary>
    ///     表示文件缓存的通用接口。
    /// </summary>
    /// <remarks>
    ///     所有缓存提供程序都应实现此接口。  
    ///     例如：<see cref=""MemoryCacheProvider""/>。
    /// </remarks>
    public interface ICacheProvider
    {
        /// <summary>
        ///     判断缓存中是否存在指定键。
        /// </summary>
        /// <param name=""key"">要检查的缓存键。</param>
        /// <returns>如果存在返回 <c>true</c>，否则返回 <c>false</c>。</returns>
        bool Contains(string key);
    }

    /// <summary>
    ///     表示内存缓存的默认实现。
    /// </summary>
    /// <inheritdoc />
    public class MemoryCacheProvider : ICacheProvider
    {
        private readonly HashSet<string> _cache = new();

        /// <inheritdoc />
        public bool Contains(string key) => _cache.Contains(key);
    }

    /// <summary>
    ///     定义下载任务的状态。
    /// </summary>
    /// <remarks>
    ///     可用于表示当前下载任务的生命周期。
    /// </remarks>
    public enum DownloadStatus
    {
        /// <summary>
        ///     下载尚未开始。
        /// </summary>
        Pending = 0,

        /// <summary>
        ///     正在下载中。
        /// </summary>
        Running = 1,

        /// <summary>
        ///     下载已完成。
        /// </summary>
        Completed = 2,

        /// <summary>
        ///     下载已失败。
        /// </summary>
        Failed = 3
    }
}

// 在 Visual Studio 中输入 /// 会自动生成基本模板（summary / param / returns）。
// 若要生成 XML 文档文件，在 .csproj 中启用：
// <PropertyGroup>
//   <GenerateDocumentationFile>true</GenerateDocumentationFile>
// </PropertyGroup>
// 若用于 Swagger，请安装 Swashbuckle.AspNetCore 并加载 XML 文件。