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; } }