C# XML 文档注释文件格式
2015-03-14 22:38
621 查看
在编写 C# 代码时,只要在注释按照格式加入 XML 文档注释,例如:
就可以通过设置项目的"属性->生成->输出->XML 文档文件",来为当前项目生成包含所有文档注释的 XML 文件。一般可用于 Visual Studio 的智能提示,或者利用 Sandcastle 等工具生成文档。
下面,我会介绍生成的 XML 文件的格式和相关规则,都以 C# 编译器生成的结果为基准。
XML 文件的根节点是
二、唯一标识符规则
唯一标识符总是
成员类型
完全限定名
成员名称中的点会被替换为
由关键字指定的类型,会被替换为相应类型的完全限定名,例如
指针类型会表示为
多维数组会表示为
泛型类型会省略掉泛型参数,并在类名后添加
如果成员中出现了对类型的泛型参数的引用,会使用
泛型方法同样会省略掉泛型参数,并在类名后添加
如果成员中出现了对方法的泛型参数的引用,会使用
泛型类型中的
对于隐式和显式类型转换方法(
一个完整的实例如下所示,其中列出了每个成员对应的唯一标识符:
/// <summary> /// 这里是类的注释。 /// </summary> public class MyClass { }
就可以通过设置项目的"属性->生成->输出->XML 文档文件",来为当前项目生成包含所有文档注释的 XML 文件。一般可用于 Visual Studio 的智能提示,或者利用 Sandcastle 等工具生成文档。
下面,我会介绍生成的 XML 文件的格式和相关规则,都以 C# 编译器生成的结果为基准。
一、XML 文档注释文件格式
XML 文档注释的文件格式非常简单,就是一个包含了所有注释的列表,一个简单的例子如下所示:XML 文件的根节点是
doc,下面包含两个子节点
assembly和
members。其中
assembly是 XML 文件对应的程序集名称,
members则包含了多个
member节点,列出了所有的注释(不区分是公共、受保护的还是私有成员)。
member节点的
name元素是一个唯一的标识符,与程序集中定义的类、方法、属性、字段等成员一一对应。在编写文档注释时指定的
cref属性,也会全部转换为标识符,而不是原先指定的成员名称。
<?xml version="1.0"?> <doc> <assembly> <name>Cyjb</name> </assembly> <members> <member name="T:Cyjb.ArrayExt"> <summary> 提供数组的扩展方法。 </summary> </member> <member name="M:Cyjb.ArrayExt.Left``1(``0[],System.Int32)"> <summary> 从当前数组的左端截取一部分。 </summary> <typeparam name="T">数组中元素的类型。</typeparam> <param name="array">从该数组返回其最左端截取的部分。</param> <param name="length">要截取的元素个数。 如果为 <c>0</c>,则返回空数组。如果大于或等于 <paramref name="array"/> 的长度, 则返回整个数组的一个浅拷贝。</param> <returns>从指定数组的左端截取的部分。</returns> <exception cref="T:System.ArgumentNullException"><paramref name="array"/> 为 <c>null</c>。</exception> <exception cref="T:System.ArgumentOutOfRangeException"><paramref name="length"/> 小于 <c>0</c>。</exception> </member> ... </members> </doc>
二、唯一标识符规则
唯一标识符总是
Type:FullName的格式,其中
Type表示对应成员的类型,
FullName是对应成员的完全限定名,中间是用
:分隔。
成员类型
Type的可能值有:
N- 命名空间。
T- 类型,包括类、接口、结构体、枚举和委托。
F- 字段。
P- 属性。
M- 方法,包括普通方法、构造函数和运算符重载。
E- 事件。
!- 错误成员,一般是由于编译器无法识别指定的成员类型,例如
<see cref="MemberNotExists"/>,就会被编译器转换为
<see cref="!:MemberNotExists"/>。
完全限定名
FullName则与成员本身的完全限定名类似,都是从命名空间的根开始,使用点分隔。不同的是:
成员名称中的点会被替换为
#,例如构造函数的名称
.ctor会替换为
#ctor。
由关键字指定的类型,会被替换为相应类型的完全限定名,例如
object会替换为
System.Object,
void会替换为
System.Void。
指针类型会表示为
*,引用类型会表示为
@
多维数组会表示为
[lowerbound:size,lowerbound:size],其中
lowerbound是数组的指定维的下限,
size是相应的大小,未指定的话就直接省略。例如
int[,]会替换为
System.Int32[0:,0:]。
泛型类型会省略掉泛型参数,并在类名后添加
`num,其中
num是泛型参数的个数。例如
SampleType<T, T2>会替换为
SampleType`2。
如果成员中出现了对类型的泛型参数的引用,会使用
`idx代替,其中
idx是相应泛型参数在类型定义中的索引。例如上面的
SampleType<T, T2>,对
T的引用会替换为
`0,对
T2的引用会替换为
`1。
泛型方法同样会省略掉泛型参数,并在类名后添加
``num,其中
num是泛型参数的个数。例如
SampleType<T, T2>.SampleMethod<T3>会替换为
SampleType`2.SampleMethod``1。
如果成员中出现了对方法的泛型参数的引用,会使用
``idx代替,其中
idx是相应泛型参数在方法定义中的索引。例如上面的
SampleType<T, T2>.SampleMethod<T3>,对
T3的引用会替换为
``0。
泛型类型中的
<和
>会被替换成
{和
},例如
IList<int>会替换为
System.Collections.Generic.IList{System.Int32}。
对于隐式和显式类型转换方法(
op_Implicit和
op_Explicit),由于往往单凭参数类型不足以唯一区分方法,因此会在方法后额外添加
~returnType,其中
returnType是方法的返回值。例如
operator SampleType(int x)会替换为
SampleType.op_Explicit(System.Int32)~SampleType。
一个完整的实例如下所示,其中列出了每个成员对应的唯一标识符:
using System.Collections.Generic; // Identifier is N:Cyjb namespace Cyjb { /// <summary> /// Identifier is T:Cyjb.SampleType /// </summary> public unsafe class SampleType { /// <summary> /// Identifier is F:Cyjb.SampleType.SampleValue /// </summary> public const int SampleValue = 0; /// <summary> /// Identifier is F:Cyjb.SampleType.SampleValue2 /// </summary> public int SampleValue2 = 0; /// <summary> /// Identifier is M:Cyjb.SampleType.#ctor /// </summary> public SampleType() { } /// <summary> /// Identifier is M:Cyjb.SampleType.#ctor(System.Int32) /// </summary> public SampleType(int value) { } /// <summary> /// Identifier is M:Cyjb.SampleType.SampleMethod /// </summary> public void SampleMethod() { } /// <summary> /// Identifier is M:Cyjb.SampleType.SampleMethod(System.Int32,System.Int32@,System.Int32*) /// </summary> public void SampleMethod(int a, ref int b, int* c) { } /// <summary> /// Identifier is M:Cyjb.SampleType.SampleMethod(System.Int32[],System.Int32[0:,0:],System.Int32[][]) /// </summary> public void SampleMethod(int[] a, int[,] b, int[][] c) { } /// <summary> /// Identifier is M:Cyjb.SampleType.SampleMethod``1(``0,``0[],System.Collections.Generic.IList{``0},System.Collections.Generic.IList{System.Collections.Generic.IList{``0[]}}) /// </summary> public void SampleMethod<T>(T a, T[] b, IList<T> c, IList<IList<T[]>> d) { } /// <summary> /// Identifier is M:Cyjb.SampleType.op_Addition(Cyjb.SampleType,Cyjb.SampleType) /// </summary> public static SampleType operator +(SampleType x, SampleType y) { return null; } /// <summary> /// Identifier is M:Cyjb.SampleType.op_Explicit(System.Int32)~Cyjb.SampleType /// </summary> public static explicit operator SampleType(int x) { return null; } /// <summary> /// Identifier is M:Cyjb.SampleType.op_Implicit(Cyjb.SampleType)~System.Int32 /// </summary> public static implicit operator int(SampleType x) { return 0; } /// <summary> /// Identifier is P:Cyjb.SampleType.SampleProperty /// </summary> public int SampleProperty { get; set; } /// <summary> /// Identifier is P:Cyjb.SampleType.Item(System.Int32) /// </summary> public int this[int index] { get { return 0; } } /// <summary> /// Identifier is T:Cyjb.SampleType.SampleDelegate /// </summary> public delegate void SampleDelegate(int a); /// <summary> /// Identifier is E:Cyjb.SampleType.SampleEvent /// </summary> public event SampleDelegate SampleEvent; /// <summary> /// Identifier is T:Cyjb.SampleType.NestedType /// </summary> public class NestedType { } /// <summary> /// Identifier is T:Cyjb.SampleType.NestedType2`1 /// </summary> public class NestedType2<T> { /// <summary> /// Identifier is M:Cyjb.SampleType.NestedType2`1.TestMethod``1(`0,``0,System.Collections.Generic.IDictionary{`0,``0}) /// </summary> public void TestMethod<T2>(T a, T2 b, IDictionary<T, T2> c) { } } } }
相关文章推荐
- 把 Visual Studio .NET 源代码文件中C# XML注释提取成工程文档
- C# : 操作Word文件的API - (将C# source中的xml注释转换成word文档)
- 把 Visual Studio .NET 源代码文件中C# XML注释提取成工程文档
- 把 Visual Studio .NET 源代码文件中C# XML注释提取成工程文档
- 把 Visual Studio .NET 源代码文件中C# XML注释提取成工程文档
- C#操纵XML文档(主要是应用程序的配置文件)
- 用C#将XML中的文字数据写如WORD文档,并控制其格式(包括字体的样式和字体大小)
- C# 加载xml文档文件及加载xml字符串
- XMLSchema.xsd 文件约束xml文档格式内容
- C#代码通过dtd验证xml文件格式是否正确
- C# XML 文档注释
- VS2005 XML注释生成XML文档文件
- C# 加载xml文档文件及加载xml字符串
- 在Visual studio 2010中为C#的“///”注释内容生成XML文档
- C# XML文档注释
- 把 Visual Studio .NET 源代码文件中C# XML注释提取成
- C#中XML文档生成实例:Elevator Scheduler测试文件的生成详解
- XML 文档注释(C# 编程指南)
- [唐胡璐] - C#将QTP结果(XML+XSL文档)转换为HTML格式
- VS2005 XML注释生成XML文档文件