C#的XML代码注释

在C/C++,JAVA中，有两种注释，一种是单行注释，即两根反斜杠(//)，另一种是多行注释，即以/*开头，以*/结尾。

在Java中，多行注释(Multiline Comment)分为两种形式:

1.普通多行注释,比如

/*
 *多行注释
 */

2.Javadoc注释,比如

/**
  *Javadoc注释
  */

当Java源文件编译的时候，Javadoc工具会读取源文件当中的Javadoc注释内容，并生成相应的HTML文档。供开发者参阅API相关的内容。

在C#中采用了另外一种形式，即XML。

为了能够在编译过程中生成XML文档，需要一种来标记来标注注释。即三根反斜杠。

下面是一个简单的例子:

namespace MyNameSpace
{
    /// <summary>
    /// 这是一个普通的类
    /// </summary>
    public class Person
    {
        /// <summary>
        /// 这是标识的ID
        /// </summary>
        public string Id { get; protected set; }
        /// <summary>
        /// 这是姓名
        /// </summary>
        public string Name { get; set; }
        /// <summary>
        /// 这是年龄
        /// </summary>
        public int Age { get; set; }

        /// <summary>
        /// 这是构造函数
        /// </summary>
        /// <param name="id">ID</param>
        /// <param name="name">姓名</param>
        /// <param name="age">年龄</param>
        public Person(string id, string name, int age)
        {
            this.Id = id;
            this.Name = name;
            this.Age = age;
        }
        /// <summary>
        /// 介绍自己啦
        /// </summary>
        public void IntroduceMyself()
        {
            Console.WriteLine("My name is {0}, My age is {1}", Name, Age);
        }
        /// <summary>
        /// 计算两者之和
        /// </summary>
        /// <param name="a">左操作数</param>
        /// <param name="b">右操作数</param>
        /// <returns>两者和</returns>
        public int calculate(int a, int b)
        {
            return a + b;
        }
        /// <summary>
        /// 讲话啦
        /// </summary>
        /// <param name="msg">讲的内容</param>
        public void saySomething(string msg)
        {
            Console.WriteLine(msg);
        }
    }
}

编译该文件:  csc /doc:test.xml test.cs

查看生成的XML文档:

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>MyNameSpace</name>
    </assembly>
    <members>
        <member name="T:MyNameSpace.Person">
            <summary>
            这是一个普通的类
            </summary>
        </member>
        <member name="M:MyNameSpace.Person.#ctor(System.String,System.String,System.Int32)">
            <summary>
            这是构造函数
            </summary>
            <param name="id">ID</param>
            <param name="name">姓名</param>
            <param name="age">年龄</param>
        </member>
        <member name="M:MyNameSpace.Person.IntroduceMyself">
            <summary>
            介绍自己啦
            </summary>
        </member>
        <member name="M:MyNameSpace.Person.calculate(System.Int32,System.Int32)">
            <summary>
            计算两者之和
            </summary>
            <param name="a">左操作数</param>
            <param name="b">右操作数</param>
            <returns>两者和</returns>
        </member>
        <member name="M:MyNameSpace.Person.saySomething(System.String)">
            <summary>
            讲话啦
            </summary>
            <param name="msg">讲的内容</param>
        </member>
        <member name="P:MyNameSpace.Person.Id">
            <summary>
            这是标识的ID
            </summary>
        </member>
        <member name="P:MyNameSpace.Person.Name">
            <summary>
            这是姓名
            </summary>
        </member>
        <member name="P:MyNameSpace.Person.Age">
            <summary>
            这是年龄
            </summary>
        </member>
    </members>
</doc>

如果是在VISUAL STUDIO，需在项目属性的生成选项卡中选中生成XML文件，并指定路径和文件名。

这样，当您在使用相应的类或者方法时，我们利用IDE自带的提示工具查看该类或该方法的简要：

Over...