营销型网站开发营销,海兴网站建设,网络架构是什么,做分销网站系统一.摘要 .Net允许开发人员在源代码中插入XML注释#xff0c;这在多人协作开发的时候显得特别有用。 C#解析器可以把代码文件中的这些XML标记提取出来#xff0c;并作进一步的处理为外部文档。 这篇文章将展示如何使用这些XML注释。 在项目开发中#xff0c;很多人并不乐意写…一.摘要 .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 namehotelId酒店Id/param /// param namelanguageCode语言码.中文为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这样的文档,我们需要了解更多的注释标签.下面是我整理的常用的注释标签: 标签名称说明语法参数summarysummary 标记应当用于描述类型或类型成员。使用 remarks 添加针对某个类型说明的补充信息。 summary 标记的文本是唯一有关 IntelliSense 中的类型的信息源它也显示在 对象浏览器 中。summary Description /summarydescription:对象的摘要。remarks使用 remarks 标记添加有关类型的信息以此补充用 summary 指定的信息。此信息显示在对象浏览器中。remarks Description /remarksdescription:成员的说明。paramparam 标记应当用于方法声明的注释中以描述方法的一个参数。 有关 param 标记的文本将显示在 IntelliSense、对象浏览器和代码注释 Web 报表中。param namename description /paramname:方法参数名。将此名称用双引号括起来 ( )。 description:参数说明。returnsreturns 标记应当用于方法声明的注释以描述返回值。returns Description /returnsdescription:返回值的说明。valuevalue 标记使您得以描述属性所代表的值。请注意当在 Visual Studio .NET 开发环境中通过代码向导添加属性时它将会为新属性添加 summary 标记。然后应该手动添加 value 标记以描述该属性所表示的值。value property-description /valueproperty-description:属性的说明example使用 example 标记可以指定使用方法或其他库成员的示例。这通常涉及使用 code 标记。example Description /exampledescription: 代码示例的说明。cc 标记为您提供了一种将说明中的文本标记为代码的方法。使用 code 将多行指示为代码。c Text /ctext :希望将其指示为代码的文本。code使用 code 标记将多行指示为代码。使用c指示应将说明中的文本标记为代码。code Content /codecontent:希望将其标记为代码的文本。exceptionexception 标记使您可以指定那些异常可被引发。此标记可用在方法、属性、事件和索引器的定义中。exception crefmember Description /exceptioncref: 对可从当前编译环境中获取的异常的引用。编译器检查到给定异常存在后将 member 转换为输出 XML 中的规范化元素名。必须将 member 括在双引号 ( ) 中。 有关如何创建对泛型类型的 cref 引用的更多信息请参见 see description:异常的说明。see seealso see 标记使您得以从文本内指定链接。使用 seealso 指示文本应该放在“另请参见”节中。see crefmember/cref: 对可以通过当前编译环境进行调用的成员或字段的引用。编译器检查给定的代码元素是否存在并将 member 传递给输出 XML 中的元素名称。应将 member 放在双引号 ( ) 中。parapara 标记用于诸如summaryremarks 或 returns 等标记内使您得以将结构添加到文本中。paracontent/paracontent:段落文本。code*提供了一种插入代码的方法。code srcsrc languagelan encodingc/src:代码文件的位置 language:代码的计算机语言 encoding:文件的编码img*用以在文档中插入图片img srcsrc/src:图片的位置相对于注释所在的XML文件file*用以在文档中插入文件在页面中表现为下载链接file srcsrc/src:文件的位置相对于注释所在的XML文件localize*提供一种注释本地化的方法名称与当前线程语言不同的子节点将被忽略localize zh-CHS中文/zh-CHS enEnglish/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 nameuserId/ 参数为正整数.br/ /// 用户Id模型属性定义参见see crefUserInfo.UserId/br/ /// 相关方法:seealso crefUserBL.GetUserId/ /// /remarks /// param nameuserId用户Id/param /// returns用户真实姓名/returns /// example /// 返回用户id为100的用户真实姓名: /// code /// private string userName string.Empty; /// userName UserBL.GetUserName(100); /// /code /// 返回的用户名可能为null,使用时要先判断:br/ /// cif(userName!null){...}/c /// /example /// exception crefSystem.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注释标签, 以及最后在帮助文档中的作用. 了解了标签的使用,在下篇文章中将告诉大家如何使用工具生成本文示例中的帮助文件.
