教程
C# 提供一种机制，供开发人员使用 XML 将其代码存档。在源代码文件中，以下代码行可以作为注释处理并放在文件中：以 /// 开始的行；在用户定义的类型（如类、委托或接口）、某成员（如字段、事件、属性或方法）或某命名空间声明之前的行。
示例
下面的示例提供对某个已存档的类型的基本概述。若要编译该示例，请键入以下命令行：
csc XMLsample.cs /doc:XMLsample.xml
这将创建 XML 文件 XMLsample.xml，您可以在浏览器中或使用 TYPE 命令查看该文件。
// XMLsample.cs
// compile with: /doc:XMLsample.xml
using System;
///
1<summary>
2 /// Class level summary documentation goes here.</summary>
///
1<remarks>
2 /// Longer comments can be associated with a type or member
3 /// through the remarks tag</remarks>
public class SomeClass { ///
1<summary>
2 /// Store for the name property</summary>
private string myName = null;
///
1<summary>
2 /// The class constructor. </summary>
public SomeClass() { // TODO: Add Constructor Logic here }
///
1<summary>
2 /// Name property </summary>
///
1<value>
2 /// A value tag is used to describe the property value</value>
public string Name { get { if ( myName == null ) { throw new Exception("Name is null"); }
return myName;
}
}
///
1<summary>
2 /// Description for SomeMethod.</summary>
///
1<param name="s"/>
Parameter description for s goes here ///
1<seealso cref="String">
2 /// You can use the cref attribute on any tag to reference a type or member
3 /// and the compiler will check that the reference exists. </seealso>
public void SomeMethod(string s) { }
///
1<summary>
2 /// Some other method. </summary>
///
1<returns>
2 /// Return results are described through the returns tag.</returns>
///
1<seealso cref="SomeMethod(string)">
2 /// Notice the use of the cref attribute to reference a specific method </seealso>
public int SomeOtherMethod() { return 0; }
///
1<summary>
2 /// The entry point for the application.
3 /// </summary>
///
1<param name="args"/>
A list of command line arguments public static int Main(String[] args) { // TODO: Add code to start application here
return 0;
}
}
代码讨论
XML 文档以 /// 开头。创建新项目时，向导将为您放入一些起始 /// 行。对这些注释的处理有一些限制：
- 文档必须是符合标准格式的 XML。如果 XML 不符合标准格式，将生成警告，并且文档文件将包含一条注释，指出遇到错误。有关符合标准格式的 XML 的更多信息，请参见 XML 词汇表。
- 开发人员可自由创建自己的标记集。有一套建议的标记（请参见“其他阅读材料”部分）。某些建议的标记具有特殊含义： *
1<param/>
标记用于描述参数。如果使用，编译器将验证参数是否存在，以及文档中是否描述了所有参数。如果验证失败，则编译器发出警告。 * cref 属性可以附加到任意标记，以提供对代码元素的引用。编译器将验证该代码元素是否存在。如果验证失败，则编译器发出警告。查找 cref 属性中描述的类型时，编译器还考虑任何 using 语句。 *
1<summary> 标记由 Visual Studio 内的“智能感知”使用，用来显示类型或成员的其他相关信息。
2
3
4
5**在 Visual Studio 开发环境中设置此编译器选项** 若要将生成的 .xml 文件用于 智能感知 功能，请使该 .xml 文件的文件名与要支持的程序集同名，然后确保该 .xml 文件放入与该程序集相同的目录中。这样，在 Visual Studio 项目中引用程序集时，也可找到该 .xml 文件。
6
7单击“配置属性”文件夹。
8
9 1. 单击“生成”属性页。
10 2. 修改“XML 文档文件”属性。
11
12
13 * <summary></summary> 描述类型成员。
14 * <remarks></remarks> 指定类或其他类型的概述信息。
15 * <param/> 在方法声明的注释中使用以描述该方法的一个参数。
16 * <returns></returns> 在方法声明的注释中使用以描述返回值。
17 * <newpara></newpara> 在注释中开始一个新段落。</summary>