频道栏目
读书频道 > 软件开发 > C# > C#高级编程(第8版)
2.11.2 XML文档
2013-10-25 15:38:44     我来说两句
收藏   我要投稿

本文所属图书 > C#高级编程(第8版)

《C 高级编程(第8版)》是C 2012和 NET 4 5高级技术的终极资源,旨在帮助读者更新、提高用C 2012和 NET 4 5编写Windows应用程序、Web应用程序、Windows 8样式应用程序的技巧。本书的顶级作者专家团队首先介  立即去当当网订购

如前所述,除了C风格的注释外,C#还有一个非常出色的功能,本章将讨论这一功能:根据特定的注释自动创建XML格式的文档说明。这些注释都是单行注释,但都以3条斜杠(///)开头,而不是通常的两条斜杠。在这些注释中,可以把包含类型和类型成员的文档说明的XML标记放在代码中。

编译器可以识别表2-10所示的标记。

表2-10

标    记 说    明
<c> 把行中的文本标记为代码,例如<c>int i = 10;</c>
<code> 把多行标记为代码
<example> 标记为一个代码示例
<exception> 说明一个异常类(编译器要验证其语法)
<include> 包含其他文档说明文件的注释(编译器要验证其语法)
<list> 把列表插入到文档中
<para> 建立文档的结构
<param> 标记方法的参数(编译器要验证其语法)
<paramref> 表示一个单词是方法的参数(编译器要验证其语法)
<permission> 说明对成员的访问(编译器要验证其语法)
<remarks> 给成员添加描述
<returns> 说明方法的返回值
<see> 提供对另一个参数的交叉引用(编译器要验证其语法)
<seealso> 提供描述中的“参见”部分(编译器要验证其语法)
 (续表)  
标    记 说    明
<summary> 提供类型或成员的简短小结
<typeparam> 用在泛型类型的注释中以说明一个类型参数
<typepararef> 类型参数的名称
<value> 描述属性
 

要了解它们的工作方式,可以在上一节的MathLibrary.cs文件中添加一些XML注释。我们给类及其Add()方法添加一个<summary>元素,也给Add()方法添加一个<returns>元素和两个<param>元素:
// MathLib.cs
namespace Wrox
{
///<summary>
/// Wrox.Math class.
/// Provides a method to add two integers.
///</summary>
public class MathLib
{
///<summary>
/// The Add method allows us to add two integers.
///</summary>
///<returns>Result of the addition (int)</returns>
///<param name="x">First number to add</param>
///<param name="y">Second number to add</param>
public int Add(int x, int y)
{
return x + y;
}
}
}

C#编译器可以把XML元素从特定的注释中提取出来,并使用它们生成一个XML文件。要让编译器为程序集生成XML文档,需在编译时指定/doc选项,后跟要创建的文件名:
csc /t:library /doc:MathLibrary.xml MathLibrary.cs

如果XML注释没有生成格式正确的XML文档,编译器就生成一个错误。

上面的代码会生成一个XML文件Math.xml,如下所示。
<?xml version="1.0"?>
<doc>
<assembly>
<name>MathLibrary</name>
</assembly>
<members>
<member name="T:Wrox.MathLibrary">
<summary>
Wrox.MathLibrary class.
Provides a method to add two integers.
</summary>
</member>
<member name=
"M:Wrox.MathLibrary.Add(System.Int32,System.Int32)">
<summary>
The Add method allows us to add two integers.
</summary>
<returns>Result of the addition (int)</returns>
<param name="x">First number to add</param>
<param name="y">Second number to add</param>
</member>
</members>
</doc>

注意,编译器自行完成了一些工作—— 它创建了一个<assembly>元素,并为该文件中的每个类型或类型成员添加一个<member>元素。每个<member>元素都有一个name特性,该特性的值是成员的全名,前面有一个字母,含义如下:"T:"表示一个类型,"F:" 表示一个字段,"M:" 表示一个成员。

您对本文章有什么意见或着疑问吗?请到论坛讨论您的关注和建议是我们前行的参考和动力  
上一篇:2.11.1 源文件中的内部注释
下一篇:2.12 C#预处理器指令
相关文章
图文推荐
排行
热门
最新书评
特别推荐

关于我们 | 联系我们 | 广告服务 | 投资合作 | 版权申明 | 在线帮助 | 网站地图 | 作品发布 | Vip技术培训 | 举报中心

版权所有: 红黑联盟--致力于做实用的IT技术学习网站