XML注释与Description标签及Java：注解（Annotation）的关系⼀.摘要
.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 报表中。
<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：代码⽂件的位置
<code>*提供了⼀种插⼊代码的⽅法。<code
src="src"language="lan"encoding="c"/>language：代码的计算机语⾔
encoding:⽂件的编码
<img>*⽤以在⽂档中插⼊图⽚<imgsrc="src"/>src：图⽚的位置，相对于注释所在的XML⽂件
<file>*⽤以在⽂档中插⼊⽂件，在页⾯中表现为
下载链接<filesrc="src"/>
的XML⽂件
<localize>*提供⼀种注释本地化的⽅法，名称与当前
线程语⾔不同的⼦节点将被忽略<localize>
<zh-CHS>中⽂</zh-CHS> <en>English</en> ...
</localize>
五.注释与帮助⽂档
java xml是什么完善注释信息的最终⽬的就是为了⽣成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注释标签, 以及最后在帮助⽂档中的作⽤.
了解了标签的使⽤，在下篇⽂章中将告诉⼤家如何使⽤⼯具⽣成本⽂⽰例中的帮助⽂件.
出处：wwwblogs/zhangziqiu/archive/2009/01/23/XmlComment.html
  要深⼊学习注解，我们就必须能定义⾃⼰的注解，并使⽤注解，在定义⾃⼰的注解之前，我们就必须要了解Java为我们提供的元注解和相关定义注解的语法。
元注解：
  元注解的作⽤就是负责注解其他注解。Java5.0定义了4个标准的meta-annotation类型，它们被⽤来提供对其它 annotation类型作说明。Java5.0定义的元注解：
    1.@Target,
    2.@Retention,
    3.@Documented,
    4.@Inherited
  这些类型和它们所⽀持的类在java.lang.annotation包中可以到。下⾯我们看⼀下每个元注解的作⽤和相应分参数的使⽤说明。
  @Target：
  　@Target说明了Annotation所修饰的对象范围：Annotation可被⽤于 packages、types（类、接⼝、枚举、Annotation类型）、类型成员（⽅法、构造⽅法、成员变量、枚举值）、⽅法参数和本地变量（如循环变量、catch参数）。在Annotation类型的声明中使⽤了target可更加明晰其修饰的⽬标。
  作⽤：⽤于描述注解的使⽤范围（即：被描述的注解可以⽤在什么地⽅）
  取值(ElementType)有：
    1.CONSTRUCTOR:⽤于描述构造器
    2.FIELD:⽤于描述域
    3.LOCAL_VARIABLE:⽤于描述局部变量
    4.METHOD:⽤于描述⽅法
    5.PACKAGE:⽤于描述包
    6.PARAMETER:⽤于描述参数
    7.TYPE:⽤于描述类、接⼝(包括注解类型) 或enum声明
  使⽤实例：　
@Target(ElementType.TYPE)
public @interface Table {
/**
* 数据表名称注解，默认值为类名称
* @return
*/
public String tableName() default "className";
}
@Target(ElementType.FIELD)
public @interface NoDBColumn {
}
  注解Table 可以⽤于注解类、接⼝(包括注解类型) 或enum声明,⽽注解NoDBColumn仅可⽤于注解类的成员变量。
  @Retention：
  @Retention定义了该Annotation被保留的时间长短：某些Annotation仅出现在源代码中，⽽被编译器丢弃；⽽另⼀些却被编译在class⽂

版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。