C# 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) { }
}
}
}
C# XML 文档注释文件格式的更多相关文章
- 转 创建 JavaScript XML 文档注释
http://www.cnblogs.com/chenxizhang/archive/2009/07/12/1522058.html 如何:创建 JavaScript XML 文档注释 Visual ...
- C# XML 文档注释
原文链接:http://www.shinater.com/DocsBuilder/help.html <summary>description</summary> 描述类型或类 ...
- C#中XML文档注释编译DLL引用到其它项目
引用地址:http://zhidao.baidu.com/link?url=jSGYEBysE4gBExtNsHCVk3vd2OK2cMlaf02cS79GdRuGueTBdFJB0btOdBYkg_ ...
- C#中的XML文档注释-推荐的文档注释标记
文档注释是为了方便自己和他人更好地理解代码所实现的功能.下面记录了一些常用的文档注释标记: <C> 用法: <c>text</c> 将说明中的文本标记为代码.例如: ...
- 在Visual studio 2010中为C#的“///”注释内容生成XML文档 .
实际上该方法适合于所有版本的Visual studio,方法很简单,设置一下Visual studio的项目属性和工具选项即可. 1.在菜单栏的“Project”中选择当前项目的“*** Proper ...
- Python之xml文档及配置文件处理(ElementTree模块、ConfigParser模块)
本节内容 前言 XML处理模块 ConfigParser/configparser模块 总结 一.前言 我们在<中我们描述了Python数据持久化的大体概念和基本处理方式,通过这些知识点我们已经 ...
- 【转】Python之xml文档及配置文件处理(ElementTree模块、ConfigParser模块)
[转]Python之xml文档及配置文件处理(ElementTree模块.ConfigParser模块) 本节内容 前言 XML处理模块 ConfigParser/configparser模块 总结 ...
- JavaEE实战——XML文档DOM、SAX、STAX解析方式详解
原 JavaEE实战--XML文档DOM.SAX.STAX解析方式详解 2016年06月22日 23:10:35 李春春_ 阅读数:3445 标签: DOMSAXSTAXJAXPXML Pull 更多 ...
- C#反序列化XML异常:在 XML文档(0, 0)中有一个错误“缺少根元素”
Q: 在反序列化 Xml 字符串为 Xml 对象时,抛出如下异常. 即在 XML文档(0, 0)中有一个错误:缺少根元素. A: 首先看下代码: StringBuilder sb = new Stri ...
随机推荐
- codeforces 258div2 A Game With Sticks(DP)
题目链接:http://codeforces.com/contest/451/problem/A 解题报告:有n跟红色的棍子横着放,m根蓝色的棍子竖着放,它们形成n*m个交点,两个人轮流在里面选择交点 ...
- 使用JDBC获取各数据库的Meta信息——表以及对应的列
先贴代码,作为草稿: 第一个是工具类, MapUtil.java [java] view plain copy import java.util.ArrayList; import java.util ...
- PHP声明
1. <!DOCTYPE> 声明位于文档中的最前面的位置,处于 <html> 标签之前.2. 此标签可告知浏览器文档使用哪种 HTML 或 XHTML 规范. <!DOC ...
- ssh tar 命令把远程文件拉回来或推过去
ssh tar 命令把远程文件拉回来或推过去 2010-09-11 21:55:35 分类: LINUX 登录22后tar 压缩/var/log目录输出到标准输入通过管道传到本地22_log. ...
- 用chrome模拟微信浏览器访问需要OAuth2.0网页授权的页面
现在很流行微信网页小游戏,用html5制作的小游戏移过来,可以放到微信浏览器中打开,关键是可以做成微信分享朋友圈的形式,大大提高游戏的传播,增强好友的游戏互动. 微信浏览器中打开网页游戏效果还不错,对 ...
- asp.net动态输出透明gif图片
要使用asp.net动态输出透明gif图片,也就是用Response.ContentType = "image/GIF". 查了国内几个中文资料都没解决,最后是在一个英文博客上找到 ...
- 一步步实现Nagios监控linux主机及飞信报警
一步步实现Nagios监控linux主机及飞信报警 上篇文章介绍了在linux主机上架设nagios监控服务,并对windows主机进行服务状态变化的监控,这次我们继续上次内容. 首先实现n ...
- 【转】js onclick用法:跳转到指定URL
使用onclick跳转到其他页面/跳转到指定url ☆如果是本页显示可以直接用location,方法如下: ①onclick="javascript:window.location.hr ...
- Linux系统排查2——CPU负载篇
本随笔介绍CPU负载的排查手段. 查看系统负载的工具:uptime,w,都能查看系统负载,系统平均负载是处于运行或不可打扰状态的进程的平均数, 可运行:运行态,占用CPU,或就绪态,等待CPU调度. ...
- Ubuntu 用户安装 MATE
MATE 是经典桌面 Gnome 2 的分支,该桌面按照 Windows 用户操作习惯设计,适合于 Windows 转投 Linux 的初级用户,MATE 做了功能改进和新增功能.如:增加窗口管理 ...