C#中的XML注释

C#中的XML注释

注:转载自http://hi.baidu.com/czlaner/blog/item/aa9251d35e7005033af3cfce.html

 

　　上篇文章提到过如何使用Sandcastle创建C#的帮助文档，这需要在源文件中插入XML注释，以“///”的形式出现。C#的“///<></>”注释在编译生成xml时候被抽取出来，是用Sandcastle自动生成CHM帮助文档必不可少的来源。

===========================================================
目录
一、常见标记
　　<summary>
　　<remarks>
　　<para>
　　<param>
　　<paramref>
　　<returns>
　　<see>
　　<seealso>
　　<example>
　　<c>
　　<code>
　　<value>
二、示例源代码
三、其它标记：
　　<typeparam>
　　<typeparamref>
　　<list>
　　<item>
　　<term>与<description>
　　<exception>
　　<include>
四、在注释中插入图片等资源
五、其它注意事项
六、参考文档
===========================================================

一、常见标记

常见的xml文档注释标记有<summary><remark><param><returns><para>等。

<summary>用于描述类型或类型成员函数，在其声明之前标注。

<remarks>用于添加有关某个类型的补充信息，比如类图（怎样插入图像资源下面第四点再叙述）。<remarks>标注可以嵌入在<summary>中，也可以跟在<summary>之后。嵌入在<summary>中会在命名空间页中对类的描述表中出现（图1）；与<summary>并列则会在类的描述页出现（图2）。

<para>可以嵌入于注释内，添加第二段说明：（此处嵌入于<summary>内）

<param>标签用于方法声明的注释中，描述方法的一个参数。语法为<param name=”paramname”>description</param>。

<paramref>用于代码注释中的某个单词引用某个参数，使文档以某种独特方式（通常是斜体）来设置该单词的格式。语法为<paramref name=”paramname”/>。

<returns>用于方法声明的注释，描述返回值。

<see>标签用于从文本内指定链接。语法为<see cref=”member”/>。

<seealso>标签指示文本放在“请参见”节中。语法为<seealso cref=”member”/>。cref=”member”对可以通过当前编译环境进行调用的成员或字段进行引用。编译器检查给定的代码元素是否存在，并将member传递给输出XML中的元素名。

上面几个标签例：

<example>指定使用方法或其它库成员的示例，常涉及<code>。

<c>将说明中的文本标记为代码。

<code>将说明中的文本多行指示为代码。

例：

<value>标签用于描述属性所代表的值。

--------------------------------------------------------------------------------------------------------------------------------

二、示例源代码

附：以上示例使用到的源代码：
//《TestClass.cs》
using System;
using System.Collections.Generic;
using System.Text;

namespace XMLTag
{
    /// <summary>
    /// This is a test class
    /// </summary>
    /// <remarks>
    ///     You may have some additional information about this class.<br/>
    ///     There's the class diagram.<br/>
    ///     <img src="ClassDiagram.png" />
    /// </remarks>
    public class TestClass
    {
        /// <summary>DoWork is a method in the TestClass class.
        ///     <para>Here's how you could make a second paragraph in a description.<br/>
        ///         The <paramref name="aParam"/> parameter takes a number.<br/>
        ///         <see cref="TestClass.aValue"/> for information about output statements.
        ///     </para>
        ///     <seealso cref="TestClass.GetZero"/>
        /// </summary>
        /// <param name="aParam">Used to indicate status.</param>
        /// <returns>Returns none.</returns>
        public static void DoWork(int aParam)
        {
        //    System.Console.WriteLine(System.String);
        }

        /// <summary>
        ///     The GetZero method.
        /// </summary>
        /// <returns>returns zero.</returns>
        /// <example> This sample shows how to call the GetZero method.
        ///     <code>
        ///     class MyClass
        ///     {
        ///         static int Main()
        ///         {
        ///             return GetZero();
        ///         }
        ///     }
        ///     </code>
        /// </example>
        public static int GetZero()
        {
            return 0;
        }

        private string _value;

        /// <value>The aValue property gets/sets the _value data member.
        /// </value>
        public string aValue
        {
            get
            {
                return _value;
            }
            set
            {
                _value = value;
            }
        }
    }  
}
The Overview：

--------------------------------------------------------------------------------------------------------------------------------

三、其它标记

<typeparam>标签用于在泛型的类型或方法声明注释中标记类型参数。语法为<typeparam name=”typename”>description</typeparam>。

<typeparamref>使文档以某种独特方式（通常是斜体）来设置单词的格式。语法为<typeparamref name=”typename”/>。

<list>创建列表。语法为<list type=”bullet” | ”number” | “table”></list>。

<item>列表中每一项都用一个<item>块描述。

<term>与<description>一般创建定义列表时，既需要指定term也需要指定description。特别地，对于表、项目符号表、编号列表，只需为description提供一个项。
例：
        /// <summary>Here is an example of a bulleted list:
        /// <list type="bullet">
        ///     <listheader>
        ///         <term>The Title</term>
        ///         <description>something</description>
        ///     </listheader>
        ///     <item>
        ///         <description>Item 1.</description>
        ///     </item>
        ///     <item>
        ///         <description>Item 2.</description>
        ///     </item>
        /// </list>
        /// </summary>

<exception>标签用于说明异常情况。语法为<exception cref=”member”>description</exception>。

<include>标签用于引用描述源代码中类型和成员的另一文件中的注释。语法为<include file=’filename’ path=’tagpath[@name=”id”]’/>。其中filename为要包含的文档的文件名，该文件名可用tagpath限定，注意filename在单引号’’中；name为注释前边的标记中的名称说明符，name具有一个id，注意id在双引号””中。

--------------------------------------------------------------------------------------------------------------------------------

四、在注释中插入图片等资源

　　在SandcastleGUI的说明中知道其可以在生成的文档中插入图片等资源，网搜却不得其法。于是抱着试试看的想法给SandcastleGUI的作者inchl发了求助邮件，令人感动的是inchl两个小时后就回复了邮件并且详细地附上了操作过程，在此再次感谢作者。
操作步骤：
Step 1：创建需要的图片资源并且把它们放在一个独立的文件夹中，注意不能含有子文件夹。
Step 2：在源代码中声明对该资源的引用，注意必须对文件名引用，不能包含路径。
　　例如：
　　/// <summary>
　　/// 　　This class does something.
　　/// </summary>
　　/// <remarks>
　　/// 　　There is a class diagram.<br/>
　　/// 　　<img src="myClassImage.png" />
　　/// </remarks>
Step 3：设置SandcastleGUI的时候在“directory to include in documentation (optional)”选项中选择放置图片资源的文件夹。
Step 4：设置好其它参数后，执行SandcastleGUI。
示例：

--------------------------------------------------------------------------------------------------------------------------------

五、其它注意事项

1. 包含编译好的xml和dll源文件的文件夹也不能含有子文件夹。
2. 注意生成CHM文件时存放该文件的文档会先被清空。
3. 生成的CHM文档不能放在带有“#”字符的路径下，否则会出现“页面不能打开”的错误。

--------------------------------------------------------------------------------------------------------------------------------

六、参考文档：

MSDN（C#编程指南）：建议的文档注释标记
http://msdn2.microsoft.com/zh-cn/library/5ast78ax(VS.80).aspx

感谢SandcastleGUI的作者inchl