一. 摘要

    .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 这样的文档, 我们需要了解更多的注释标签. 下面是我整理的常用的注释标签:

五. 注释与帮助文档

完善注释信息的最终目的就是为了生成 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

深入理解 Java：注解（Annotation）自定义注解入门

@Target(ElementType.TYPE)
public @interface Table {
    /**
     * 数据表名称注解，默认值为类名称
     * @return
     */
    public String tableName() default "className";
}
@Target(ElementType.FIELD)
public @interface NoDBColumn {
}

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
public @interface Column {
    public String name() default "fieldName";
    public String setFuncName() default "setField";
    public String getFuncName() default "getField"; 
    public boolean defaultDBValue() default false;
}

@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface Column {
    public String name() default "fieldName";
    public String setFuncName() default "setField";
    public String getFuncName() default "getField"; 
    public boolean defaultDBValue() default false;
}

/**
 * 
 * @author peida
 *
 */
@Inherited
public @interface Greeting {
    public enum FontColor{BULE,RED,GREEN};
    String name();
    FontColor fontColor() default FontColor.GREEN;
}

package annotation;
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**

水果名称注解
@author peida


*/
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface FruitName {
String value() default "";
}

package annotation;
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**

水果颜色注解
@author peida


/
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface FruitColor {
/**
* 颜色枚举
* @author peida
*
/
public enum Color{BULE,RED,GREEN};
</span><span style="color: rgba(0, 128, 0, 1)">/**</span><span style="color: rgba(0, 128, 0, 1)">
 * 颜色属性
 * </span><span style="color: rgba(128, 128, 128, 1)">@return</span>
 <span style="color: rgba(0, 128, 0, 1)">*/</span><span style="color: rgba(0, 0, 0, 1)">
Color fruitColor() </span><span style="color: rgba(0, 0, 255, 1)">default</span><span style="color: rgba(0, 0, 0, 1)"> Color.GREEN;

}

package annotation;
import annotation.FruitColor.Color;
public class Apple {
@FruitName(</span>"Apple"<span style="color: rgba(0, 0, 0, 1)">)
</span><span style="color: rgba(0, 0, 255, 1)">private</span><span style="color: rgba(0, 0, 0, 1)"> String appleName;

@FruitColor(fruitColor</span>=<span style="color: rgba(0, 0, 0, 1)">Color.RED)
</span><span style="color: rgba(0, 0, 255, 1)">private</span><span style="color: rgba(0, 0, 0, 1)"> String appleColor;




</span><span style="color: rgba(0, 0, 255, 1)">public</span> <span style="color: rgba(0, 0, 255, 1)">void</span><span style="color: rgba(0, 0, 0, 1)"> setAppleColor(String appleColor) {
    </span><span style="color: rgba(0, 0, 255, 1)">this</span>.appleColor =<span style="color: rgba(0, 0, 0, 1)"> appleColor;
}
</span><span style="color: rgba(0, 0, 255, 1)">public</span><span style="color: rgba(0, 0, 0, 1)"> String getAppleColor() {
    </span><span style="color: rgba(0, 0, 255, 1)">return</span><span style="color: rgba(0, 0, 0, 1)"> appleColor;
}


</span><span style="color: rgba(0, 0, 255, 1)">public</span> <span style="color: rgba(0, 0, 255, 1)">void</span><span style="color: rgba(0, 0, 0, 1)"> setAppleName(String appleName) {
    </span><span style="color: rgba(0, 0, 255, 1)">this</span>.appleName =<span style="color: rgba(0, 0, 0, 1)"> appleName;
}
</span><span style="color: rgba(0, 0, 255, 1)">public</span><span style="color: rgba(0, 0, 0, 1)"> String getAppleName() {
    </span><span style="color: rgba(0, 0, 255, 1)">return</span><span style="color: rgba(0, 0, 0, 1)"> appleName;
}

</span><span style="color: rgba(0, 0, 255, 1)">public</span> <span style="color: rgba(0, 0, 255, 1)">void</span><span style="color: rgba(0, 0, 0, 1)"> displayName(){
    System.out.println(</span>"水果的名字是：苹果"<span style="color: rgba(0, 0, 0, 1)">);
}

}

 package annotation;
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
/**

水果供应者注解
@author peida


/
@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface FruitProvider {
/**
* 供应商编号
* @return
/
public int id() default -1;
 </span><span style="color: rgba(0, 128, 0, 1)">/**</span><span style="color: rgba(0, 128, 0, 1)">
  * 供应商名称
  * </span><span style="color: rgba(128, 128, 128, 1)">@return</span>
  <span style="color: rgba(0, 128, 0, 1)">*/</span>
 <span style="color: rgba(0, 0, 255, 1)">public</span> String name() <span style="color: rgba(0, 0, 255, 1)">default</span> ""<span style="color: rgba(0, 0, 0, 1)">;
 
 </span><span style="color: rgba(0, 128, 0, 1)">/**</span><span style="color: rgba(0, 128, 0, 1)">
  * 供应商地址
  * </span><span style="color: rgba(128, 128, 128, 1)">@return</span>
  <span style="color: rgba(0, 128, 0, 1)">*/</span>
 <span style="color: rgba(0, 0, 255, 1)">public</span> String address() <span style="color: rgba(0, 0, 255, 1)">default</span> ""<span style="color: rgba(0, 0, 0, 1)">;

}