你瞭解C#中的XML註釋嗎

時間 2019-12-30

標籤瞭解 c# xml 註釋欄目 C# 简体版

原文原文鏈接

XML註釋是什麼

在VS中編寫C#代碼時，若是在類、變量、方法等上方連續輸入三個「\」，VS會自動爲咱們生成一段XML註釋模板。經過這段模板，咱們能夠將代碼的註釋規範化，造成一份XML註釋文檔（能夠在項目「生成」設置中對保存路徑進行配置）。這樣，不只VS能夠讀取，還可讓如Swagger等第三方插件使用。插件

如下代碼展現了經常使用的文檔標記：code

/// <summary>
/// 動物工廠
/// </summary>
public class AnimalFactory
{
    /// <summary>
    /// 建立類型爲 <typeparamref name="TAnimal"/> 的動物
    /// </summary>
    /// <typeparam name="TAnimal">動物的類型</typeparam>
    /// <param name="name">動物的名字</param>
    /// <returns>一個繼承於 <see cref="Animal"/> 抽象類的實體</returns>
    /// <exception cref="ArgumentException">當 <paramref name="name"/> 爲 <c>null</c>、<c>""</c> 或空白字符串時拋出</exception>
    /// <example>
    /// 你能夠經過以下方式建立 <see cref="Dog"/> 的實例
    /// <code>
    /// var dog = AnimalFactory.CreateAnimal{Dog}(「小白」);
    /// Console.WriteLine(dog.Name);
    /// </code>
    /// </example>        
    /// <remarks><see cref="CreateAnimal{TAnimal}(string)"/> 是 <c>AnimalFactory</c> 的靜態方法</remarks>
    public static TAnimal CreateAnimal<TAnimal>(string name) where TAnimal : Animal, new()
    {
        if (string.IsNullOrWhiteSpace(name))
            throw new ArgumentException("動物名字不能爲空", nameof(name));

        return new TAnimal()
        {
            Name = name
        };
    }
}

/// <summary>
/// 動物
/// </summary>
public abstract class Animal
{
    private string _name;

    /// <summary>
    /// 名字
    /// </summary>
    /// <value>Name屬性 get/set 的值是字符串字段：_name</value>
    public string Name
    {
        get => _name;
        set => _name = value;
    }
}

/// <summary>
/// 狗
/// </summary>
public class Dog : Animal
{

}

將dll與xml提供給他人使用時，VS中看到的就是這樣：xml

//
// 摘要:
//     動物工廠
public class AnimalFactory
{
    public AnimalFactory();

    //
    // 摘要:
    //     建立類型爲 TAnimal 的動物
    //
    // 參數:
    //   name:
    //     動物的名字
    //
    // 類型參數:
    //   TAnimal:
    //     動物的類型
    //
    // 返回結果:
    //     一個繼承於 ConsoleAppForXML.Animal 抽象類的實體
    //
    // 異常:
    //   T:System.ArgumentException:
    //     當 name 爲 null、"" 或空白字符串時拋出
    //
    // 言論：
    //     ConsoleAppForXML.AnimalFactory.CreateAnimal``1(System.String) 是 AnimalFactory
    //     的靜態方法
    public static TAnimal CreateAnimal<TAnimal>(string name) where TAnimal : Animal, new();
}