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

更新:2007 年 11 月

下面的示例提供对某个已存档的类型的基本概述。

示例

// 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;
    }
}
// This .xml file was generated with the previous code sample.
<?xml version="1.0"?>
<doc>
    <assembly>
        <name>xmlsample</name>
    </assembly>
    <members>
        <member name="T:SomeClass">
            <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:SomeClass.m_Name">
            <summary>
            Store for the name property</summary>
        </member>
        <member name="M:SomeClass.#ctor">
            <summary>The class constructor.</summary> 
        </member>
        <member name="M:SomeClass.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:SomeClass.SomeOtherMethod">
            <summary>
            Some other method. </summary>
            <returns>
            Return results are described through the returns tag.</returns>
            <seealso cref="M:SomeClass.SomeMethod(System.String)">
            Notice the use of the cref attribute to reference a specific method </seealso>
        </member>
        <member name="M:SomeClass.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:SomeClass.Name">
            <summary>
            Name property </summary>
            <value>
            A value tag is used to describe the property value</value>
        </member>
    </members>
</doc>

编译代码

若要编译该示例,请键入以下命令行:

csc XMLsample.cs /doc:XMLsample.xml

这将创建 XML 文件 XMLsample.xml,您可以在浏览器中或使用 TYPE 命令查看该文件。

可靠编程

XML 文档以 /// 开头。创建新项目时,向导将为您放入一些起始 /// 行。对这些注释的处理有一些限制:

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

  • 开发人员可自由创建自己的标记集。有一套建议的标记(请参见“其他阅读材料”部分)。某些建议的标记具有特殊含义:

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

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

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

      说明:

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

请参见

任务

“XML 文档”示例

概念

C# 编程指南

参考

/doc(处理文档注释)(C# 编译器选项)

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