NET中的规范标准注释(一) -- XML注释标签讲解
一.摘要
.Net容许开发人员在源代码中插入XML注释，这在多人协做开发的时候显得特别有用。 C#解析器能够把代码文件中的这些XML标记提取出来，并做进一步的处理为外部文档。 这篇文章将展现如何使用这些XML注释。 在项目开发中，不少人并不乐意写繁杂的文档。可是，开发组长但愿代码注释尽量详细；项目规划人员但愿代码设计文档尽量详尽；测试、检查人员但愿功能说明书尽量详细等等。若是这些文档都被要求写的话，保持它们同步比进行一个战役还痛苦。html
为什么不把这些信息保存在一个地方呢？？最明显想到的地方就是代码的注释中；可是你很难通览程序，而且有些须要这些文档的人并不懂编码。最好的办法是经过使用XML注释来解决这些问题。代码注释、用户手册、开发人员手册、测试计划等不少文档能够很方便的从XML注释中得到。本文讲解.Net中常用的XML注释.主要使用C#语言j,.Net平台支持的其余语言使用的XML注释格式基本相同.而且在本系列文章的下一讲中讲解如何使用工具将XML注释内容转化为帮助文档.程序员
二.XML注释概述
全部的XML注释都在三个向前的斜线以后(///)。两条斜线表示是一个注释，编译器将忽略后面的内容。三条斜线告诉编译器，后面是XML注释，须要适当地处理。c#
当开发人员输入三个向前的斜线后，Microsoft Visual Studio .NET IDE 自动检查它是否在类或者类成员的定义的前面。若是是的话，Visual Studio .NET IDE 将自动插入注释标记，开发人员只须要增长些额外的标记和值。下面就是在成员函数前增长三个斜线，自动增长的注释好比:浏览器
/// <summary> /// 获得指定酒店的酒店信息 /// </summary> /// <param name="hotelId">酒店Id</param> /// <param name="languageCode">语言码.中文为zh-cn</param> /// <returns>酒店信息对象</returns> [OperationContract] OutHotelInfo GetHotelInfoByHotelId(string loginName, string loginPassword, string hotelId, string languageCode);
这里嵌入的summary,param,returns标记仅仅是Visual Studio可以识别的一部分标记，然而在智能感知IntelliSense中，并无把c#规范中全部的标记列出来，遗失的部分只能用手工插入。 这些手工标记是很是有用的，若是恰当地设置他们，对导出成外部说明文件将很是有帮助。函数
三.将注释生成XML文件
在代码中添加的注释信息, 能够单独提取出来, 生成XML文件. 在制做最后的帮助文件的时候会使用到这些注释XML文件.工具
默认状况下是不生成注释XML文件的.每一个项目能够生成一个XML文件,须要咱们在项目属性中进行设置:post
如上图所示,在项目的"属性页"->"生成"中, 勾选"XML文档文件"复选框,便可在编译时生成注释XML文件.生成路径默认是和dll文件在同一个文件夹下,也能够自行修改.注意此处填写的是相对路径.测试
四.常见注释标签列表
注释的使用很简单,可是咱们使用到的注释不多.这是由于大部分项目中注释的做用仅仅是给程序员本身看.若是想要生成相似MSDN这样的文档,咱们须要了解更多的注释标签.下面是我整理的经常使用的注释标签:编码
| 标签名称spa |
说明 |
语法 |
参数 |
| <summary> |
<summary> 标记应当用于描述类型或类型成员。使用 <remarks> 添加针对某个类型说明的补充信息。 <summary> 标记的文本是惟一有关 IntelliSense 中的类型的信息源，它也显示在 对象浏览器 中。 |
<summary> Description </summary> |
description:对象的摘要。 |
| <remarks> |
使用 <remarks>标记添加有关类型的信息，以此补充用 <summary> 指定的信息。此信息显示在对象浏览器中。 |
<remarks> Description </remarks> |
description:成员的说明。 |
| <param> |
<param> 标记应当用于方法声明的注释中，以描述方法的一个参数。 有关 <param> 标记的文本将显示在 IntelliSense、对象浏览器和代码注释 Web 报表中。 |
<paramname='name'> description </param> |
name:方法参数名。将此名称用双引号括起来 (" ")。 description:参数说明。 |
| <returns> |
<returns> 标记应当用于方法声明的注释，以描述返回值。 |
<returns> Description </returns> |
description:返回值的说明。 |
| <value> |
<value> 标记使您得以描述属性所表明的值。请注意，当在 Visual Studio .NET 开发环境中经过代码向导添加属性时，它将会为新属性添加 <summary> 标记。而后，应该手动添加 <value> 标记以描述该属性所表示的值。 |
<value> property-description </value> |
property-description:属性的说明 |
| <example> |
使用 <example> 标记能够指定使用方法或其余库成员的示例。这一般涉及使用 <code> 标记。 |
<example> Description </example> |
description: 代码示例的说明。 |
| <c> |
<c> 标记为您提供了一种将说明中的文本标记为代码的方法。使用 <code> 将多行指示为代码。 |
<c> Text </c> |
text :但愿将其指示为代码的文本。 |
| <code> |
使用 <code> 标记将多行指示为代码。使用<c>指示应将说明中的文本标记为代码。 |
<code> Content </code> |
content:但愿将其标记为代码的文本。 |
| <exception> |
<exception> 标记使您能够指定哪些异常可被引起。此标记可用在方法、属性、事件和索引器的定义中。 |
<exception cref="member"> Description </exception> |
cref: 对可从当前编译环境中获取的异常的引用。编译器检查到给定异常存在后，将 member 转换为输出 XML 中的规范化元素名。必须将 member 括在双引号 (" ") 中。 有关如何建立对泛型类型的 cref 引用的更多信息，请参见 <see> description:异常的说明。 |
| <see> <seealso> |
<see> 标记使您得以从文本内指定连接。使用 <seealso> 指示文本应该放在“另请参见”节中。 |
<seecref="member"/> |
cref: 对能够经过当前编译环境进行调用的成员或字段的引用。编译器检查给定的代码元素是否存在，并将 member 传递给输出 XML 中的元素名称。应将 member 放在双引号 (" ") 中。 |
| <para> |
<para> 标记用于诸如<summary>，<remarks> 或 <returns> 等标记内，使您得以将结构添加到文本中。 |
<para>content</para> |
content:段落文本。 |
| <code>* |
提供了一种插入代码的方法。 |
<code src="src" language="lan" encoding="c"/> |
src:代码文件的位置 language:代码的计算机语言 encoding:文件的编码 |
| <img>* |
用以在文档中插入图片 |
<imgsrc="src"/> |
src:图片的位置，相对于注释所在的XML文件 |
| <file>* |
用以在文档中插入文件，在页面中表现为下载连接 |
<filesrc="src"/> |
src:文件的位置，相对于注释所在的XML文件 |
| <localize>* |
提供一种注释本地化的方法，名称与当前线程语言不一样的子节点将被忽略 |
<localize> <zh-CHS>中文</zh-CHS> <en>English</en> ... </localize> |
|
五.注释与帮助文档
完善注释信息的最终目的就是为了生成MSDN同样的程序帮助文档,此文档将在项目整个生命周期中被各类角色使用:开发人员经过此文档维护程序, 测试人员经过此文档了解业务逻辑, 项目管理人员将此文档用做项目说明等等.
因此要了解列表中这些不常见的注释究竟有何做用,就要和最终的帮助文档关联起来.下面经过示例讲解注释标签在帮助文件中的做用.有关如何生成帮助文件,将在本系列下一篇文章中讲解.
先简单看一下帮助文件的样子.咱们都看过MSDN帮助文档,使用注释XML文件生成的帮助文件后缀名是chm,打开后和MSDN基本同样:
本示例的命名空间是XmlCommentClassDemo, 其中包含两个类:
UserBL是包含方法的类.
UserInfo是一个模型类.里面只有UserId和UserName两个属性.
(1)类注释
看一下UserBL类的注释代码:
/// <summary> /// 用户对象业务逻辑层. /// </summary> /// <remarks> /// 2009.01.01: 建立. ziqiu.zhang <br/> /// 2009.01.23: 增长GetUserName和GetUserId方法. ziqiu.zhang <br/> /// </remarks> public class UserBL {...}
Summary标签的内容在命名空间类列表中显示,如上图.remarks标签的内容则显示在类页面中,以下图:
对比之前的注释规范,下面的注释是咱们规定在建立一个新的文件时须要添加到头部的注释:
/*************************************************************************************** * * * * File Name : HotelCommentHeaderInfo.cs * * Creator : ziqiu.zhang * * Create Time : 2008-09-17 * * Functional Description : 酒店的点评头模型。包括酒店实体对应的点评头，酒店的OutHotelInfo信息 * ，酒店实体的Tag信息集合。 * * Remark : * * * * Copyright (c) eLong Corporation. All rights reserved. * ***************************************************************************************/
添加此注释块的目的很好.可是很难推广.由于这段注释并不能被编译器识别,也没法添加到注释XML文件中用于生成帮助文件. 格式不容易记忆,想添加的时候只能从别的复制过来后修改.公司缺乏完善的Code Review机制因此最后不少文件都没有此注释块.
相比较使用.NET本身的注释语言,不只"敏捷",并且会成为帮助文件中的描述.
(2)方法注释
类的注释比较简单.为了样式经常使用注释标签的效果, 我在方法的注释中使用了尽量多的注释标签.代码以下:
/// <summary> /// 根据用户Id获得用户名. /// <para> /// 此处添加第二段Summary信息,在MSDN中不多使用.因此不推荐使用. /// </para> /// </summary> /// <remarks> /// 若是没有找到用户则返回null.<br/> /// <paramref name="userId"/> 参数为正整数.<br/> /// 用户Id模型属性定义参见<see cref="UserInfo.UserId"/><br/> /// 相关方法:<seealso cref="UserBL.GetUserId"/> /// </remarks> /// <param name="userId">用户Id</param> /// <returns>用户真实姓名</returns> /// <example> /// 返回用户id为100的用户真实姓名: /// <code> /// private string userName = string.Empty; /// userName = UserBL.GetUserName(100); /// </code> /// 返回的用户名可能为null,使用时要先判断:<br/> /// <c>if(userName!=null){...}</c> /// </example> /// <exception cref="System.ApplicationException"> /// 若是用户Id小于0则抛出此异常 /// </exception> public static string GetUserName(long userId) { string result = string.Empty; if (userId < 0) { throw new System.ApplicationException(); } else if (userId == 0) { result = null; } else { result = "Robert"; } return result; }
接下来经过图片进行详细讲解.首先是查看类成员时的截图:
点击方法后的截图:
须要注意的几点:
1) 最开始seealso标签添加在了remarks标签中,因此在See Also区域没有添加上方法的链接. 解决方法是把seealso标签放在summary标签中.
2) 异常类的cref属性须要设置成编译器能够识别的类, 这样才能够在帮助文档中点击.好比上面的System.ApplicationException异常点击后进入微软的在线MSDN查询.若是是本身定义的异常, 须要此异常类也在你的帮助文件中.通常提供注释XML和依赖DLL便可.
(3) 属性的注释
属性的注释也很简单.和类不一样的地方在于属性要使用<value>标签而不是<remarks>进行描述:
private string m_UserName = string.Empty; /// <summary> /// 用户真实姓名 /// </summary> /// <value>用户真实姓名字符串.默认值为空.</value> public string UserName { get { return m_UserName; } set { m_UserName = value; } }
效果如图:
六.总结
本文讲解了.NET中的XML注释标签, 以及最后在帮助文档中的做用.
了解了标签的使用,在下篇文章中将告诉你们如何使用工具生成本文示例中的帮助文件.
出处：http://www.cnblogs.com/zhangziqiu/archive/2009/01/23/XmlComment.html