关于.NET程序中XML文档注释的总结

 

程序的注释在程序的编写和维护中扮演着相当重要的角色，.NET程序中的XML文档注释将程序注释的编写提高到了一个新的层次：在编写注释的同时，说明文档也就随之而生了，这给我们带来了极大的方便。那么，究竟怎么样编写XML文档注释呢？我根据自己掌握的知识，列出了以下4点：

 

1    在编写.NET程序XML文档注释2种格式：

l 使用单行分隔符“///”

l 使用多行分隔符“/** */”

本人推荐使用单行分隔符来编写XML文档注释。

 

2    XML doc 注释不是元数据；它们不包括在编译的程序集中，因此无法通过反射对其进行访问。

 

3    编译器将处理任何为有效 XML 的标记。下列标记提供了用户文档中常用的功能：

<c>	<para>	<see>*
<code>	<param>*	<seealso>*
<example>	<paramref>	<summary>
<exception>*	<permission>*	<typeparam>*
<include>*	<remarks>	<typeparamref>
<list>	<returns>	<value>

（* 表示编译器验证语法。）

 

4    编译器为代码中被标记为生成文档的每一个构造生成一个 ID 字符串。ID 字符串唯一地标识构造。处理 XML 文件的程序可以使用 ID 字符串标识文档应用于的相应 .NET Framework 元数据/反射项。XML 文件不是代码的分层表示形式，它是一个平面列表，每一个元素都有一个生成的 ID。

编译器在生成 ID 字符串时遵循下列规则：

l 不在字符串中放置空白。

l ID 字符串的第一部分通过单个字符后跟一个冒号来标识被标识成员的种类。使用下列成员类型：

字符		说明
N	命名空间 不可将文档注释添加到命名空间中，但是可以对它们进行 cref 引用（在受支持的位置）。
T	类型：类、接口、结构、枚举、委托
F	字段
P	属性（包括索引程序或其他索引属性）
M	方法（包括一些特殊方法，例如构造函数、运算符等）
E	事件
!	错误字符串 字符串的其余部分会提供有关此错误的信息。C# 编译器为无法解析的链接生成错误信息。

 

以下是C#代码示例:

// compile with: /doc:DocFileName.xml

 

/// <summary>

/// Class level summary documentation goes here.</summary>

/// <remarks>

/// Longer comments can be associated with a type or member

/// through the remarks tag</remarks>

public class TestClass

{

    /// <summary>

    /// Store for the name property</summary>

    private string _name = null;

 

    /// <summary>

    /// The class constructor. </summary>

    public TestClass()

    {

        // TODO: Add Constructor Logic here

    }

 

    /// <summary>

    /// Name property </summary>

    /// <value>

    /// A value tag is used to describe the property value</value>

    public string Name

    {

        get

        {

            if (_name == null)

            {

                throw new System.Exception("Name is null");

            }

            return _name;

        }

    }

 

    /// <summary>

    /// Description for SomeMethod.</summary>

    /// <param name="s"> Parameter description for s goes here</param>

    /// <seealso cref="System.String">

    /// You can use the cref attribute on any tag to reference a type or member

    /// and the compiler will check that the reference exists. </seealso>

    public void SomeMethod(string s)

    {

    }

 

    /// <summary>

    /// Some other method. </summary>

    /// <returns>

    /// Return results are described through the returns tag.</returns>

    /// <seealso cref="SomeMethod(string)">

    /// Notice the use of the cref attribute to reference a specific method </seealso>

    public int SomeOtherMethod()

    {

        return 0;

    }

 

    /// <summary>

    /// The entry point for the application.

    /// </summary>

    /// <param name="args"> A list of command line arguments</param>

    static int Main(System.String[] args)

    {

        // TODO: Add code to start application here

        return 0;

    }

}

XML文档输出为:

<?xml version="1.0" ?>

- <doc>

- <assembly>

  <name>XMLComment</name>

  </assembly>

- <members>

- <member name="T:TestClass">

  <summary>Class level summary documentation goes here.</summary>

  <remarks>Longer comments can be associated with a type or member through the remarks tag</remarks>

  </member>

- <member name="F:TestClass._name">

  <summary>Store for the name property</summary>

  </member>

- <member name="M:TestClass.#ctor">

  <summary>The class constructor.</summary>

  </member>

- <member name="M:TestClass.SomeMethod(System.String)">

  <summary>Description for SomeMethod.</summary>

  <param name="s">Parameter description for s goes here</param>

  <seealso cref="T:System.String">You can use the cref attribute on any tag to reference a type or member and the compiler will check that the reference exists.</seealso>

  </member>

- <member name="M:TestClass.SomeOtherMethod">

  <summary>Some other method.</summary>

  <returns>Return results are described through the returns tag.</returns>

  <seealso cref="M:TestClass.SomeMethod(System.String)">Notice the use of the cref attribute to reference a specific method</seealso>

  </member>

- <member name="M:TestClass.Main(System.String[])">

  <summary>The entry point for the application.</summary>

  <param name="args">A list of command line arguments</param>

  </member>

- <member name="P:TestClass.Name">

  <summary>Name property</summary>

  <value>A value tag is used to describe the property value</value>

  </member>

  </members>

  </doc>