使用.NET中的XML注释(一) -- XML注释标签讲解
使用.NET中的XML注释(一) -- XML注释标签讲解
一.摘要
.Net允许开发人员在源代码中插入XML注释,这在多人协作开发的时候显得特别有用。 C#解析器可以把代码文件中的这些XML标记提取出来,并作进一步的处理为外部文档。 这篇文章将展示如何使用这些XML注释。 在项目开发中,很多人并不乐意写繁杂的文档。但是,开发组长希望代码注释尽可能详细;项目规划人员希望代码设计文档尽可能详尽;测试、检查人员希望功能说明书尽可能详细等等。如果这些文档都被要求写的话,保持它们同步比进行一个战役还痛苦。
为何不把这些信息保存在一个地方呢??最明显想到的地方就是代码的注释中;但是你很难通览程序,并且有些需要这些文档的人并不懂编码。最好的办法是通过使用XML注释来解决这些问题。代码注释、用户手册、开发人员手册、测试计划等很多文档可以很方便的从XML注释中获得。本文讲解.Net中经常使用的XML注释.主要使用C#语言j,.Net平台支持的其他语言使用的XML注释格式基本相同.并且在本系列文章的下一讲中讲解如何使用工具将XML注释内容转化为帮助文档.
二.XML注释概述
所有的XML注释都在三个向前的斜线之后(///)。两条斜线表示是一个注释,编译器将忽略后面的内容。三条斜线告诉编译器,后面是XML注释,需要适当地处理。
当开发人员输入三个向前的斜线后,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文件,需要我们在项目属性中进行设置:
如上图所示,在项目的"属性页"->"生成"中, 勾选"XML文档文件"复选框,即可在编译时生成注释XML文件.生成路径默认是和dll文件在同一个文件夹下,也可以自行修改.注意此处填写的是相对路径.
四.常见注释标签列表
注释的使用很简单,但是我们使用到的注释很少.这是因为大部分项目中注释的作用仅仅是给程序员自己看.如果想要生成类似MSDN这样的文档,我们需要了解更多的注释标签.下面是我整理的常用的注释标签:
标签名称 |
说明 |
语法 |
参数 |
<summary> |
<summary> 标记应当用于描述类型或类型成员。使用 <remarks> 添加针对某个类型说明的补充信息。 <summary> 标记的文本是唯一有关 IntelliSense 中的类型的信息源,它也显示在 对象浏览器 中。 |
<summary> Description </summary> |
description:对象的摘要。 |
<remarks> |
使用 <remarks> 标记添加有关类型的信息,以此补充用 <summary> 指定的信息。此信息显示在对象浏览器中。 |
<remarks> Description </remarks> |
description:成员的说明。 |
<param> |
<param> 标记应当用于方法声明的注释中,以描述方法的一个参数。 有关 <param> 标记的文本将显示在 IntelliSense、对象浏览器和代码注释 Web 报表中。 |
<param name='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> 指示文本应该放在“另请参见”节中。 |
<see cref="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>* |
用以在文档中插入图片 |
<img src="src"/> |
src:图片的位置,相对于注释所在的XML文件 |
<file>* |
用以在文档中插入文件,在页面中表现为下载链接 |
<file src="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注释标签, 以及最后在帮助文档中的作用.
了解了标签的使用,在下篇文章中将告诉大家如何使用工具生成本文示例中的帮助文件.
转载于:https://www.cnblogs.com/mingyongcheng/archive/2011/06/28/2092011.html
使用.NET中的XML注释(一) -- XML注释标签讲解相关推荐
- aop中joinpoint_Spring AOP示例教程–方面,建议,切入点,JoinPoint,注释,XML配置...
aop中joinpoint Spring Framework is developed on two core concepts – Dependency Injection and Aspect O ...
- “在XML文件中给代码加注释”请注意注释的位置
先科普一下eclipse加注释的快捷键: eclipse中编辑Java文件时,注释和取消注释的快捷键都是: "CTRL + / " 编辑xml文件时,注释:CTRL + SHIFT ...
- 您如何在PHP中解析和处理HTML / XML?
如何解析HTML / XML并从中提取信息? #1楼 QueryPath很好,但是要小心"跟踪状态",因为如果您没有意识到这意味着什么,那可能意味着您浪费了大量的调试时间来试图找出 ...
- MyEclipse for Windows 关于 java、jsp、xml、js、html 等文件的注释快捷键及注释格式介绍
文章目录 java 的注释 单行注释 多行注释 文本注释 jsp 的注释 第一种 第二种 第三种 css 的注释 js 的注释 单行注释 奇葩的单行注释 多行注释 文档注释 xml 的注释 html ...
- 无法使用struts2注释_带有注释且没有struts.xml文件的Struts 2 Hello World示例
无法使用struts2注释 This is the second article in the series of Struts 2 Tutorials. If you have directly c ...
- XML文件怎么添加注释
注释以 <!-- 开始并以 --> 结束, 例如 <!--注释内容-->. 注释可以出现在文档序言中,包括文档类型定义 (DTD):文档之后:或文本内容中. 注释不能出现在属性 ...
- C#中XmlDocument读取和创建 XML 文档
系列文章目录 C#处理XML 数据的技术方法总结 XmlDocument读取和创建 XML 文档 XmlWriter类提供一种快速非缓存的只进 XML 数据生成方式 XmlReader类提供一种快速非 ...
- python中利用lxml模块解析xml文件报错XMLSyntaxError: Opening and ending tag mismatch
今天在代码中第一次使用lxml解析xml文件时出错了, XMLSyntaxError: Opening and ending tag mismatch: keyEffectiveDate line 2 ...
- Android 中自定义控件和属性(attr.xml,declare-styleable,TypedArray)的方法和使用
一. 在res/values 文件下定义一个attrs.xml 文件.代码如下: <?xml version="1.0" encoding="utf-8" ...
最新文章
- crontab定时任务运行
- 终端编译opengl程序编译运行_ubuntu编译opengl和demo之二(glfw版本)
- angular java_带有Angular JS的Java EE 7 –第1部分
- Eclipse Juno上带有GlassFish的JavaEE 7
- Java内存模型常见问题
- Linux中的软硬连接
- 自定义一个月份选择器插件
- 情人节集体撤档,《肥龙过江》改网播,线上首映会成为常态吗?
- 浅谈编程-----非计算机专业以及非培训班的一些感悟
- LAMP架构调优(九)——Apache Rewrite功能实战
- Xamarin.Form 超链接 用手势实现
- Atitit js nodejs 图像处理压缩缩放算法 attilax总结
- 处理 Win 10 开机后输入法不加载问题
- PPT怎么切换不同的母版
- 跌落测试 包装跌落测试
- 如何在百度地图上标注坐标点?
- ibatis3 一个小bug
- 把数据库中的数据写出到excel表格中
- thinkphp网站提示缓存文件写入失败
- EC20连接阿里云操作流程,AT_MQTT协议连接,详细
热门文章
- java 连接sqlserver2005_JAVA用jdbc连接SQLServer2005
- sgolayfilt函数_Matlab中Savitzky-Golay filtering(最小二乘平滑滤波)函数sgolayfilt的使用方法...
- 理解矩阵 的一些评论
- 对大量转载贴识别算法的研究
- 为什么都在吹鸿蒙,真的是吹爆鸿蒙
- 超出网络bios会话限制_如何设置网络以防止数据丢失
- c语言编程*字母图形,BIT网教c语言练习_编程复习1输出图形
- eval并发 shell_Shell 实现多任务并发
- android 活动说明,Android – 如何发送GCM推送通知以及要加载哪些活动的说明?
- navicat中文版安装