本教程展示如何使用 XML 将代码存档。
教程
C# 提供一种机制,供开发人 员使用 XML 将其代码存档。在源代码文件中,以下代码行可以 作为注释处理并放在文件中:以 /// 开始的行;在用户定义的 类型(如类、委托或接口)、某成员(如字段、事件、属性或方法) 或某命名空间声明之前的行。
示例
下面的示例提供对某个已存档的类型的基本概述。若要编译该示例 ,请键入以下命令行:
csc XMLsampl e.cs /doc:XMLsample.xml
这将创建 XML 文件 XMLsample.xml,您可以 在浏览器中或使用 TYPE 命令查看该文件。
// XMLsample.cs
// compile with: /doc:XMLsample.xml
us ing System;
/// <
sum mary>
/// Class level su mmary documentation goes here. <
/summary>
/// <
re marks>
/// Longer commen ts can be associated with a ty pe or member
/// through t he remarks tag<
/remarks>
public class SomeClass
{
/// <
summary>
/// Store for the name pro perty<
/summary>
pr ivate string myName = null;
/// <
summary>
/// The class constructor. <
/summary>
public SomeClass()
{
// TODO: Add Constructor Logi c here
}
// / <
summary>
/// Na me property <
/summary>
/// <
value>
/ // A value tag is used to desc ribe the property value<
/va lue>
public string Na me
{
get
{
if ( myName == null )
{
throw new Exception(" Name is null");
}< br>
r eturn myName;
}
}
/// <
summary&g t;
/// Description for S omeMethod.<
/summary>
/// <
param name="s">
Parameter description for s go es here<
/param>
// / <
seealso cref="String"> ;
/// You can use the cr ef attribute on any tag to ref erence a type or member
/// and the compiler will che ck that the reference exists. <
/seealso>
public void SomeMethod(string s)
{
}
/// <
summary>
/// Some oth er method. <
/summary>
/// <
returns>
/// Return results are describ ed through the returns tag.< ;
/returns>
/// <
se ealso cref="SomeMethod(string) ">
/// Notice the use of the cref attribute to refe rence a specific method <
/s eealso>
public int So meOtherMethod()
{
return 0;
}
/// <
summary>
/// The entry point for the appli cation.
/// <
/summary >
/// <
param name= "args">
A list of command l ine arguments<
/param>
public static int Main(Str ing[] args)
{
/ / TODO: Add code to start appl ication here
ret urn 0;
}
}
代码讨 论
XML 文档以 /// 开头。创建新项目时 ,向导将为您放入一些起始 /// 行。对这些注释的处理有一些 限制:
文档必须是符合标准格式的 X ML。如果 XML 不符合标准格式,将生成警告,并且文档文件 将包含一条注释,指出遇到错误。有关符合标准格式的 XML 的 更多信息,请参见 XML 词汇表。
开发人员 可自由创建自己的标记集。有一套建议的标记(请参见“其他阅读材 料”部分)。某些建议的标记具有特殊含义:
& lt;
param>
标记用于描述参数。如果使用,编译器 将验证参数是否存在,以及文档中是否描述了所有参数。如果验证失 败,则编译器发出警告。
cref 属性可以附 加到任意标记,以提供对代码元素的引用。编译器将验证该代码元素 是否存在。如果验证失败,则编译器发出警告。查找 cref 属 性中描述的类型时,编译器还考虑任何 using 语句。
<
summary>
标记由 Visu al Studio 内的“智能感知”使用,用来显示类型或成员 的其他相关信息。
示例 输出
以下是从上面的类生成的 XML 文件:< br>
<
?xml version="1.0"? >
<
doc>
< ;
assembly>
<
n ame>
xmlsample<
/name>
< br> <
/assembly>
<
members>
& lt;
member name="T:SomeClass"&g t;
<
summary& gt;
Class level summary documentation goes he re.<
/summary>
<
remarks>
Longer comments can be a ssociated with a type or membe r
through the remarks tag<
/remarks>
<
/member>
<
member name="F:SomeC lass.myName">
<
summary>
Store for the name property <
/summary>
&l t;
/member>
<
m ember name="M:SomeClass.#ctor" >
<
summar y>
The class constructor.< ;
/summary>
<
/member>
<
mem ber name="M:SomeClass.SomeMeth od(System.String)">
<
summary>
Description for SomeM ethod.<
/summary>
<
param name="s">
Parameter description for s g oes here<
/param>
<
seealso cref="T:Sy stem.String">
You can use the cref attribu te on any tag to reference a t ype or member
and the compiler will check th at the reference exists. <
/ seealso>
<
/me mber>
<
member name="M:SomeClass.SomeOtherMe thod">
<
s ummary>
Some other method. <
/summary> ;
<
returns&g t;
Return resul ts are described through the r eturns tag.<
/returns>
<
seealso cref= "M:SomeClass.SomeMethod(System .String)">
N otice the use of the cref attr ibute 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"& gt;
A list of command line arg uments<
/param>
<
/member>
& lt;
member name="P:SomeClass.Na me">
<
sum mary>
Name p roperty <
/summary>
<
value>
A value tag is used t o describe the property value& lt;
/value>
<
/ member>
<
/members >
<
/doc>
注意 XML 文件并不提供有关类型和成员的完整信息( 例如,它不包含任何类型信息)。若要获得有关类型或成员的完整信 息,文档文件必须与实际类型或成员上的反射一起使用。