C# XML文檔

C# XML文檔

文檔注釋是用于記錄類型或成員的嵌入式XML。

文檔注釋緊接在類型或成員聲明之前，并以三個(gè)斜杠開頭：

/// <summary>Cancels a command.</summary>
public void Cancel() { 
   ... 
}

多行注釋可以這樣做：

/// <summary>
/// Cancels a command
/// </summary>
public void Cancel() { 
   ... 
}

或者我們可以使用多行文檔命令??/ ** * /：

/**
   <summary> Cancels a command. </summary>
*/
public void Cancel() { 
   ... 
}

如果使用 / doc 指令編譯，編譯器提取并整理文檔注釋到單個(gè)XML文件中。

標(biāo)準(zhǔn)XML文檔標(biāo)記

以下是Visual Studio和文檔生成器識(shí)別的標(biāo)準(zhǔn)XML標(biāo)記：

• <summary>...</summary>
  標(biāo)記類型或成員的摘要；通常是單個(gè)短語或句子。
• <remarks>...</remarks>
  標(biāo)記描述類型或成員的其他文本。
• <param name="name">...</param>
  說明方法的參數(shù)。
• <returns>...</returns>
  說明方法的返回值。
• <exception [cref="type"]>...</exception>
  列出方法可能拋出的異常。
• <permission [cref="type"]>...</permission>
  設(shè)置記錄的類型或成員所需的IPermission類型。
• <example>...</example>
  標(biāo)記一個(gè)例子。
• <c>...</c>
  標(biāo)記內(nèi)嵌程式碼片段。
• <code>...</code>
  標(biāo)記多行代碼示例。
• <see cref="member">...</see>
  標(biāo)記到另一個(gè)類型或成員的內(nèi)聯(lián)交叉引用。
• <seealso cref="member">...</seealso>
  交叉引用另一個(gè)類型或成員。
• <paramref name="name"/>
  引用<summary>或<remarks>標(biāo)記中的參數(shù)。

  <list type=[ bullet | number | table ]>
     <listheader>
        <term>...</term>
        <description>...</description>
     </listheader>
     <item>
        <term>...</term>
        <description>...</description>
     </item>
  </list>
  

  創(chuàng)建項(xiàng)目符號(hào)，編號(hào)或表格樣式的列表。
• <para>...</para>
  將內(nèi)容格式化為單獨(dú)的段落。
• <include file="filename" path="tagpath[@name="id"]">...</para>
  合并包含文檔的外部XML文件。