C# XML文档

C# XML文档

文档注释是用于记录类型或成员的嵌入式XML。

文档注释紧接在类型或成员声明之前，并以三个斜杠开头：

/// <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 指令编译，编译器提取并整理文档注释到单个XML文件中。

标准XML文档标记

以下是Visual Studio和文档生成器识别的标准XML标记：

• <summary>...</summary>
  标记类型或成员的摘要；通常是单个短语或句子。
• <remarks>...</remarks>
  标记描述类型或成员的其他文本。
• <param name="name">...</param>
  说明方法的参数。
• <returns>...</returns>
  说明方法的返回值。
• <exception [cref="type"]>...</exception>
  列出方法可能抛出的异常。
• <permission [cref="type"]>...</permission>
  设置记录的类型或成员所需的IPermission类型。
• <example>...</example>
  标记一个例子。
• <c>...</c>
  标记内嵌程式码片段。
• <code>...</code>
  标记多行代码示例。
• <see cref="member">...</see>
  标记到另一个类型或成员的内联交叉引用。
• <seealso cref="member">...</seealso>
  交叉引用另一个类型或成员。
• <paramref name="name"/>
  引用<summary>或<remarks>标记中的参数。

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

  创建项目符号，编号或表格样式的列表。
• <para>...</para>
  将内容格式化为单独的段落。
• <include file="filename" path="tagpath[@name="id"]">...</para>
  合并包含文档的外部XML文件。