C#教程 - 标准XML标签（Standard XML Documentation Tags）

更新记录
转载请注明出处：
2022年9月22日 发布。
2022年9月10日 从笔记迁移到博客。

标准XML标签（Standard XML Documentation Tags）

<summary>    //简要说明
<param>     //参数说明
<returns>    //返回值说明
<example>    //实例说明
<code>          //代码说明
<seealso>    //see also 选项说明
<value>     //描述属性

标记使用方法：
https://docs.microsoft.com/zh-cn/dotnet/csharp/programming-guide/xmldoc/recommended-tags-for-documentation-comments

<summary>...</summary>

Indicates the tool tip that IntelliSense should display for the type or member.
Typically, a single phrase or sentence.

<remarks>...</remarks>

Additional text that describes the type or member.
Documentation generators pick this up and merge it into the bulk of a type or member’s description.

<param name="name">...</param>

Explains a parameter on a method.

<returns>...</returns>

Explains the return value for a method.

<exception [cref="type"]>...</exception>

Lists an exception that a method might throw (cref refers to the exception type).
cref指示异常的类型

<permission [cref="type"]>...</permission>

Indicates an IPermission type required by the documented type or member.

<example>...</example>

Denotes an example (used by documentation generators).
This usually contains both description text and source code
(source code is typically within a or tag).

<c>...</c>

Indicates an inline code snippet. This tag is usually used within an block.

<code>...</code>

Indicates a multiline code sample. This tag is usually used within an block.
一般放置在中

<see cref="member">...</see>

Inserts an inline cross-reference to another type or member.
HTML documentation generators typically convert this to a hyperlink.
The compiler emits a warning if the type or member name is invalid.

<seealso cref="member">...</seealso>

Cross-references another type or member.
Documentation generators typically write this
into a separate “See Also” section at the bottom of the page.

<paramref name="name"/>

References a parameter from within a

or tag.

<list>...</list>

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

Instructs documentation generators to emit a bulleted, numbered, or table-style list.

<para>...</para>

Instructs documentation generators to format the contents into a separate paragraph.

<include>...</include>

<include file='filename' path='tagpath[@name="id"]'>
  ...
</include>

Merges an external XML file that contains documentation. The path attribute denotes an XPath query to a specific element in that file.

注释实例

/// <summary>
/// DataStorage is used to persist and retrieve
/// employee data from the files
/// </summary>
class DataStorage
{
    /// <summary>
    /// Save an employee object to a file
    /// named with the employee name
    /// </summary>
    /// <remarks>
    /// This method uses
    /// <seealso cref="System.IO.FileStream"/>
    /// in addition to
    /// <seealso cref="System.IO.StreamWriter"/>
    /// </remarks>
    /// <param name="employee">
    /// The employee to persist to a file</param>
    /// <data>January 1, 2000</date>
    public static void Store(Employee employee)
    {
        // ...
    }
    /** <summary>
    * Loads up an employee object
    * </summary>
    * <remarks>
    * This method uses
    * <seealso cref="System.IO.FileStream"/>
    * in addition to
    * <seealso cref="System.IO.StreamReader"/>
    * </remarks>
    * <param name="firstName">
    * The first name of the employeee</param>
    * <param name="lastName">
    * The last name of the employee</param>
    * <returns>
    * The employee object corresponding to the names
    * </returns>
    * <date>January 1, 2000</date>**/
    public static Employee Load(string firstName, string lastName)
    {
        // ...
    }
}

配置项目的XML注释文档导出

在.csproj 项目配置文件中，添加以下代码

<PropertyGroup>
  <DocumentationFile>SomeFile.xml</DocumentationFile>
</PropertyGroup>

作用：
智能提示（IntelliSense），比如Visual Studio中
使用第三方工具生成代码的文档

第三方XML生成API文档工具

NDoc http://ndoc.sourceforge.net/
Sandcastle https://github.com/EWSoftware/SHFB
XmlCommentMarkDownGenerator https://github.com/Pxtl/XmlCommentMarkDownGenerator
GhostDoc http://submain.com/
编译器输出XML文档：https://docs.microsoft.com/zh-cn/dotnet/csharp/language-reference/compiler-options/doc-compiler-option