一.摘要

.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 将自动插入注释标记,开发人员只需要增加些额外的标记和值。下面就是在成员函数前增加三个斜线,自动增加的注释比如:

  1. /// <summary>
  2. /// 得到指定酒店的酒店信息
  3. /// </summary>
  4. /// <param name="hotelId">酒店Id</param>
  5. /// <param name="languageCode">语言码.中文为zh-cn</param>
  6. /// <returns>酒店信息对象</returns>
  7. [OperationContract]
  8. 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 报表中。

<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类的注释代码:

  1. /// <summary>
  2. /// 用户对象业务逻辑层.
  3. /// </summary>
  4. /// <remarks>
  5. /// 2009.01.01: 创建. ziqiu.zhang <br/>
  6. /// 2009.01.23: 增加GetUserName和GetUserId方法. ziqiu.zhang <br/>
  7. /// </remarks>
  8. public class UserBL
  9. {...}

Summary标签的内容在命名空间类列表中显示,如上图.remarks标签的内容则显示在类页面中,如下图:

对比以前的注释规范,下面的注释是我们规定在创建一个新的文件时需要添加到头部的注释:

  1. /***************************************************************************************
  2. * *
  3. * * File Name : HotelCommentHeaderInfo.cs
  4. * * Creator : ziqiu.zhang
  5. * * Create Time : 2008-09-17
  6. * * Functional Description : 酒店的点评头模型。包括酒店实体对应的点评头,酒店的OutHotelInfo信息
  7. * ,酒店实体的Tag信息集合。
  8. * * Remark :
  9. * *
  10. * * Copyright (c) eLong Corporation. All rights reserved.
  11. * ***************************************************************************************/

添加此注释块的目的很好.但是很难推广.因为这段注释并不能被编译器识别,也无法添加到注释XML文件中用于生成帮助文件. 格式不容易记忆,想添加的时候只能从别的复制过来后修改.公司缺少完善的Code Review机制所以最后很多文件都没有此注释块.

相比较使用.NET自己的注释语言,不仅"敏捷",而且会成为帮助文件中的描述.

(2)方法注释

类的注释比较简单.为了样式常用注释标签的效果, 我在方法的注释中使用了尽可能多的注释标签.代码如下:

  1. /// <summary>
  2. /// 根据用户Id得到用户名.
  3. /// <para>
  4. /// 此处添加第二段Summary信息,在MSDN中很少使用.所以不推荐使用.
  5. /// </para>
  6. /// </summary>
  7. /// <remarks>
  8. /// 如果没有找到用户则返回null.<br/>
  9. /// <paramref name="userId"/> 参数为正整数.<br/>
  10. /// 用户Id模型属性定义参见<see cref="UserInfo.UserId"/><br/>
  11. /// 相关方法:<seealso cref="UserBL.GetUserId"/>
  12. /// </remarks>
  13. /// <param name="userId">用户Id</param>
  14. /// <returns>用户真实姓名</returns>
  15. /// <example>
  16. /// 返回用户id为100的用户真实姓名:
  17. /// <code>
  18. /// private string userName = string.Empty;
  19. /// userName = UserBL.GetUserName(100);
  20. /// </code>
  21. /// 返回的用户名可能为null,使用时要先判断:<br/>
  22. /// <c>if(userName!=null){...}</c>
  23. /// </example>
  24. /// <exception cref="System.ApplicationException">
  25. /// 如果用户Id小于0则抛出此异常
  26. /// </exception>
  27. public static string GetUserName(long userId)
  28. {
  29. string result = string.Empty;
  30. if (userId < 0)
  31. {
  32. throw new System.ApplicationException();
  33. }
  34. else if (userId == 0)
  35. {
  36. result = null;
  37. }
  38. else
  39. {
  40. result = "Robert";
  41. }
  42. return result;
  43. }

接下来通过图片进行详细讲解.首先是查看类成员时的截图:

点击方法后的截图:

需要注意的几点:

1) 最开始seealso标签添加在了remarks标签中,所以在See Also区域没有添加上方法的连接. 解决方法是把seealso标签放在summary标签中.

2) 异常类的cref属性需要设置成编译器可以识别的类, 这样才可以在帮助文档中点击.比如上面的System.ApplicationException异常点击后进入微软的在线MSDN查询.如果是自己定义的异常, 需要此异常类也在你的帮助文件中.一般提供注释XML和依赖DLL即可.

(3) 属性的注释

属性的注释也很简单.和类不同的地方在于属性要使用<value>标签而不是<remarks>进行描述:

  1. private string m_UserName = string.Empty;
  2. /// <summary>
  3. /// 用户真实姓名
  4. /// </summary>
  5. /// <value>用户真实姓名字符串.默认值为空.</value>
  6. public string UserName
  7. {
  8. get { return m_UserName; }
  9. set { m_UserName = value; }
  10. }

效果如图:

六.总结

本文讲解了.NET中的XML注释标签, 以及最后在帮助文档中的作用.

了解了标签的使用,在下篇文章中将告诉大家如何使用工具生成本文示例中的帮助文件.

出处:http://www.cnblogs.com/zhangziqiu/archive/2009/01/23/XmlComment.html

使用.NET中的XML注释(一) -- XML注释标签讲解的更多相关文章

  1. NET中的规范标准注释(一) -- XML注释标签讲解

    一.摘要 .Net允许开发人员在源代码中插入XML注释,这在多人协作开发的时候显得特别有用. C#解析器可以把代码文件中的这些XML标记提取出来,并作进一步的处理为外部文档. 这篇文章将展示如何使用这 ...

  2. java web开发中的奇葩事web.xml中context-param中的注释

    同事提交了代码.结果除同事之外,其他人全部编译报错.报错说web.xml中配置的一个bean 没有定义.按照报错提示,各种找,无果. 由于代码全部都是提交到svn主干,之前也没有做过备份,只能一步一步 ...

  3. NET中的规范标准注释-- XML注释标签讲解

    一.摘要 .Net允许开发人员在源代码中插入XML注释,这在多人协作开发的时候显得特别有用. C#解析器可以把代码文件中的这些XML标记提取出来,并作进一步的处理为外部文档. 这篇文章将展示如何使用这 ...

  4. 根据注释生成xml和从nuget包中复制xml显示到swagger

    生成xml到输出目录 从注释生成xml 在要生成xml的项目的csproj中添加如下代码, 生成的xml名称为项目名称.xml. 比如该项目叫做Abp.Application, 则xml名为 Abp. ...

  5. IDEA XML注释与取消注释快捷键

    IntelliJ IDEA和eclipse中编辑Java文件时,注释和取消注释的快捷键都是: "CTRL + / " 编辑xml文件时, 注释:CTRL + SHIFT + / 取 ...

  6. XML文件怎么添加注释

    注释以 <!-- 开始并以 --> 结束,例如 <!--注释内容-->.   注释可以出现在文档序言中,包括文档类型定义 (DTD):文档之后:或文本内容中. 注释不能出现在属 ...

  7. XML注释与取消注释快捷键

    IntelliJ IDEA和eclipse中编辑Java文件时,注释和取消注释的快捷键都是: "CTRL + / " 编辑xml文件时, 注释:CTRL + SHIFT + / 取 ...

  8. PHP中使用DOM读取解析XML属性值一例

    先看XML文件结构,与常见的文件略有不同,数据并不是用闭合标签保存的,而是直接保存在属性值中. <?xml version="1.0" encoding="utf- ...

  9. Python连载43-current中的map函数、xml文件

    一.current中的map函数 1.map(fn,*iterable,timeout=None) (1)跟map函数相类似(2)函数需要异步执行(3)timeout代表超时时间 (4)map和sub ...

随机推荐

  1. mysql插入一张表里的数据到另一张表

    公司的一个项目,做报表--要关联的表结构比较多,最后决定把要用的数据集合到一张新表中,需要用到以下的sql语法......分享下: web开发中,我们经常需要将一个表的数据插入到另外一个表,有时还需要 ...

  2. MYSQL数据库学习笔记1

      MYSQL数据库学习笔记1 数据库概念 关系数据库 常见数据库软件 SQL SQL的概念 SQL语言分类 数据库操作 创建数据库 查看数据库的定义 删除数据库 修改数据库 创建表 数据类型 约束 ...

  3. POI 百万数据导出

    poi 导出主类 package test; import java.io.File; import java.io.FileOutputStream; import java.lang.reflec ...

  4. 大话设计模式之PHP篇 - 策略模式

    什么是策略模式? 定义:策略模式定义了一系列的算法,并将每一个算法封装起来,而且使它们还可以相互替换.策略模式让算法独立于使用它的客户而独立变化. 组成:抽象策略角色: 策略类,通常由一个接口或者抽象 ...

  5. INSPIRED启示录 读书笔记 - 第5章 产品管理与软件开发

    保持融洽的合作关系 形成合作关系的关键是双方承认彼此平等——任何一方不从属于另一方,产品经理负责定义正确的产品,开发团队负责正确地开发产品,双方相互依赖 产品经理要求开发团队完成任务,必须先取得他们的 ...

  6. Hessian与Spring整合

    1.服务端与Spring的整合 1.1:web.xml中配置控制器 <servlet> <servlet-name>hessian</servlet-name> & ...

  7. 【P2514】工厂选址(贪心)

    看到题了不首先应该看看数据范围确定一下算法么,这个题的数据范围大约可以支持到O(nmlogm),所以肯定不是搜索什么的,DP貌似至少也要n^2m,所以可以想一些其他的.对于题目的输入,我们发现这些输入 ...

  8. 【codevs3031】最富有的人(字典树)

    网址:http://codevs.cn/problem/3031/ 这是蒟蒻写的第一道字典树……听说出市选题的神犇要出字符串,于是就赶紧滚去学了学(然而高精度算字符串算法?) 简单来说,字典树就是把一 ...

  9. linux基础(9)-获取时间

    获取今天日期 date +%Y-%m-%d date +%y-%m-%d date  +%F   获取昨天日期 date -d yesterday +%F date -d -1day +%F     ...

  10. CDH- cdh kafka已经卸载了,但是服务器还有kafka-topics这些命令可用,导致重新安装kafka出现问题

    cdh界面删除并不会将 kafka数据删除,需要将kafka集群节点 var/local/kafka/data 清理掉 然后将zk brokers/topics 下的topic也清理掉