如何：使用 XML 文档功能（C# 编程指南）
下面的示例提供文档类型的基本概述。
// 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 文件生成了与上面的代码示例。<?xml version="1.0"?>
<doc>
<assembly>
namexmlsampleAMP_LT/nameAMP_GT
</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
通过注释 tagAMP_LT/remarksAMP_GT
</member>
member name="F:SomeClass.m_Name"
<summary>
名称的 propertyAMP_LT/summaryAMP_GT 存储
</member>
member name="M:SomeClass.#ctor"
summary类 constructor.AMP_LT/summaryAMP_GT
</member>
member name="M:SomeClass.SomeMethod(System.String)"
<summary>
Description for SomeMethod.</summary>
param name="s" 中的参数声明转到 hereAMP_LT/paramAMP_GT
<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)"
通知使用 cref 特性引用特定方法 AMP_LT/seealsoAMP_GT
</member>
member name="M:SomeClass.Main(System.String[])"
<summary>
The entry point for the application.</summary>
param name="args" 命令行 argumentsAMP_LT/paramAMP_GT 列表
</member>
member name="P:SomeClass.Name"
<summary>
name 属性 AMP_LT/summaryAMP_GT
<value>
值标记用于描述属性 valueAMP_LT/valueAMP_GT
</member>
</members>
</doc>
编译代码
若要编译该示例，请键入以下命令行:
csc XMLsample.cs /doc:XMLsample.xml
这将创建 XML 文件 XMLsample.xml，使用类型的命令，您可以在浏览器或。
可靠编程
XML 文档以 /// 开头。当您创建新项目时，该向导为您放置一些起始 ///行。对这些注释的处理有一些限制：
文档必须是格式良好的 XML。如果 XML 格式不正确，将生成警告，并且文档文件将包含添加的注释遇到错误。
开发人员可自由创建自己的标记集。具有建议的标记集 (请参见其他阅读材料部分)。某些建议的标记具有特殊含义：
<param> 标记用于描述参数。如果使用，编译器将验证参数是否存在，以及文档中是否描述了所有参数。如果验证失败，编译器会发出警告。
cref 特性可以附加到任意标记，以提供对代码元素的引用。编译器将验证该代码元素是否存在。如果验证失败，编译器会发出警告。编译器在查找 cref 特性中描述的类型时，会考虑所有的 using 语句。
<summary> 标记由 Visual Studio 内的“Intellisense”使用，用来显示类型或成员的其他相关信息。
 注意 |
|---|
| XML 文件不提供有关类型和成员的完整信息 (例如，它不包含任何类型信息)。若要获得有关类型或成员的完整信息，文档文件必须与实际类型或成员上的反射一起使用。 |