XML文檔注釋

1.前言

在 Visual C# 中，你可以通過以下方式為代碼創建文檔（///）：將特殊注釋字段中的 XML 元素包含在源代碼中注釋引用的代碼塊的前面，例如：

/// <summary>  
/// This class performs an important function. /// </summary>  
public class MyClass {}  

使用 /doc 選項進行編譯時，編譯器會在源代碼中搜索所有 XML 標記，並創建一個 XML 文檔文件。 若要基於編譯器生成的文件創建最終文檔，可以創建一個自定義工具，也可以使用 SandCastle 等工具。

2.建議的文檔注釋標記

標記 用途 <c> 將文本設置為類似代碼的字體 <code> 將一行或多行源代碼或程序輸出設置為某種字體 <example> 表示所含的是示例 <exception> 標識方法可能引發的異常 <include> 包括來自外部文件的 XML <list> 創建列表或表 <para> 用於將結構添加到文本中 <param> 描述方法或構造函數的參數 <paramref> 確認某個單詞是參數名 <permission> 描述成員的安全性和訪問權限 <summary> 描述一種類型 <returns> 描述方法的返回值 <see> 指定鏈接 <seealso> 生成“請參見”項 <summary> 描述類型的成員 <value>        描述屬性

3.一個簡單示例

using System; /// <summary>
/// ClassName:SomeClass /// Version:1.0 /// Date:2018/10/26 /// Author:Kyle /// </summary>
/// <remarks>
/// 本類僅是一個示例教學類，不完成具體的工作 /// </remarks>
public class SomeClass { /// <summary>
     /// 內部私有變量，存儲名稱</summary>
    private string myName = null; public SomeClass() { //
         // TODO: Add Constructor Logic here //  } /// <summary>
    /// 名稱屬性 </summary>
    /// <value>
    ///本屬性為只讀屬性，返回用戶名</value>
    public string Name { get { if ( myName == null ) { throw new Exception("Name is null"); } return myName; } } /// <summary>
    /// 本方法是沒有進行具體構建</summary>
    /// <param name="s"> 入口參數S是一個String類型</param>
    /// <seealso cref="String">
    ///String類型的信息</seealso>
    public void SomeMethod(string s) { } /// <summary>
    /// 本方法仍然沒有進行具體構建</summary>
    /// <returns>
    /// 返回值始終為0.</returns>
    /// <seealso cref="SomeMethod(string)">
    /// 參看SomeMethod(string)方法的說明 </seealso>
    public int SomeOtherMethod() { return 0; } /// <summary>
     /// 該應用程序的入口 /// </summary>
    /// <param name="args"> 入口參數集合</param>
     public static int Main(String[] args) { //
         // TODO: Add code to start application here //          return 0; } }