XML文档注释

1.前言

在 Visual C# 中，你可以通过以下方式为代码创建文档（///）：将特殊注释字段中的 XML 元素包含在源代码中注释引用的代码块的前面，例如：

/// <summary>  
///  This class performs an important function.  
/// </summary>  
public class MyClass {}  

使用 /doc 选项进行编译时，编译器会在源代码中搜索所有 XML 标记，并创建一个 XML 文档文件。 若要基于编译器生成的文件创建最终文档，可以创建一个自定义工具，也可以使用 SandCastle 等工具。

2.建议的文档注释标记

标记        用途

<c>        将文本设置为类似代码的字体

<code>        将一行或多行源代码或程序输出设置为某种字体

<example>    表示所含的是示例

<exception>    标识方法可能引发的异常

<include>       包括来自外部文件的 XML

<list>        创建列表或表

<para>        用于将结构添加到文本中

<param>        描述方法或构造函数的参数

<paramref>    确认某个单词是参数名

<permission>    描述成员的安全性和访问权限

<summary>    描述一种类型

<returns>    描述方法的返回值

<see>        指定链接

<seealso>    生成“请参见”项

<summary>    描述类型的成员

<value>        描述属性

3.一个简单示例

using System;
/// <summary>
/// ClassName:SomeClass
/// Version:1.0
/// Date:2018/10/26
/// Author:Kyle
/// </summary>
/// <remarks>
/// 本类仅是一个示例教学类，不完成具体的工作
/// </remarks>
public class SomeClass
{
     /// <summary>
     /// 内部私有变量，存储名称</summary>
    private string myName = null;
     public SomeClass()
     {
         //
         // TODO: Add Constructor Logic here
         //
     }
   
    /// <summary>
    /// 名称属性 </summary>
    /// <value>
    ///本属性为只读属性，返回用户名</value>
    public string Name
    {
       get
       {
          if ( myName == null )
          {
             throw new Exception("Name is null");
          }
             
          return myName;
       }
    }
    /// <summary>
    /// 本方法是没有进行具体构建</summary>
    /// <param name="s"> 入口参数S是一个String类型</param>
    /// <seealso cref="String">
    ///String类型的信息</seealso>
    public void SomeMethod(string s)
    {
    }
    /// <summary>
    /// 本方法仍然没有进行具体构建</summary>
    /// <returns>
    /// 返回值始终为0.</returns>
    /// <seealso cref="SomeMethod(string)">
    /// 参看SomeMethod(string)方法的说明 </seealso>
    public int SomeOtherMethod()
    {
       return 0;
    }
    /// <summary>
     /// 该应用程序的入口
    /// </summary>
    /// <param name="args"> 入口参数集合</param>
     public static int Main(String[] args)
     {
         //
         // TODO: Add code to start application here
         //
         return 0;
     }
}