如何:使用 XML 文档功能(C# 编程指南)

更新:2011 年 4 月

XML 文档提供了一种记录代码的有效方式。 以下示例提供了基本概述。

示例

// If compiling from the command line, compile with: /doc:YourFileName.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 : TestInterface
{
    /// <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;
    }

    public int InterfaceMethod(int n)
    {
        return n * n;
    }

    /// <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;
    }
}

/// <summary>
/// Documentation that describes the interface goes here.
/// </summary>
/// <remarks>
/// Details about the interface go here.
/// </remarks>
interface TestInterface
{
    /// <summary>
    /// Documentation that describes the method goes here.
    /// </summary>
    /// <param name="n">
    /// Parameter n requires an integer argument.
    /// </param>
    /// <returns>
    /// The method returns an integer.
    /// </returns>
    int InterfaceMethod(int n);
}

下面的 .xml 文件是由前面的示例生成的。 请注意,来自接口定义的注释包括在实现该接口的类中。

                          

编译代码

若要编译该示例,您可以键入以下命令行:csc XMLsample.cs /doc:XMLsample.xml。

此命令会创建 XML 文件 XMLsample.xml,您可以在浏览器中或在字处理器中查看该文件。

另外,在**“解决方案资源管理器”中,右击项目的名称,然后单击“属性”。 在“生成”选项卡上,选择“输出”部分中的“XML 文档文件”**,然后为 .xml 文件输入名称。

可靠编程

XML 文档以 /// 开头。 在您创建新项目时,IDE 将为您添加一些 /// 行。 处理这些注释时有以下限制:

  • 文档必须是格式正确的 XML。 如果 XML 格式不正确,将生成警告,并且文档文件会包含一条注释,指出已经遇到错误。

  • 开发人员可创建自己的标记集。 但是,建议使用具有特殊含义的标记集(参见本主题的“参见”部分),如以下示例所述:

    • <param> 标记用于描述参数。 如果使用此标记,则编译器会验证参数是否存在,以及文档中是否描述了所有参数。 如果验证失败,则编译器发出警告。

    • cref 特性可以附加到任意标记,以提供对代码元素的引用。 编译器将验证此代码元素是否存在。 如果验证失败,则编译器发出警告。 编译器在查找 cref 特性中描述的类型时,会考虑所有的 using 语句。

    • <summary> 标记由 Visual Studio 内的“Intellisense”使用,用来显示类型或成员的其他相关信息。

      提示

      XML 文件未提供有关类型和成员的完整信息。 例如,它不包含任何类型信息。 若要获得有关类型或成员的完整信息,文档文件必须与实际类型或成员上的反射一起使用。

请参见

参考

/doc(C# 编译器选项)

XML 文档注释(C# 编程指南)

概念

C# 编程指南

修订记录

日期

修订记录

原因

2011 年 4 月

向示例中添加了一个接口。

客户反馈