C# 註釋及說明

using System;
/// <summary>
/// ClassName:SomeClass
/// Version:1.0
/// Date:2001/6/21
/// Author:cniter
/// </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;
     }
}

爲了使用C＃提供的XML註釋功能，你的註釋應該使用特殊的註釋語法（///）開頭。在///之後，你可以使用預先定義的標籤註釋你的代碼，也可以插入你自己定義的標籤。你定製的標籤將會在隨後加入到生成的註釋文檔中。

預定義的標籤            用處

<c> 將說明中的文本標記爲代碼

<code> 提供了一種將多行指示爲代碼的方法

<example> 指定使用方法或其他庫成員的示例

<exception> 允許你指定可能發生的異常類

<include> 允許你引用描述源代碼中類型和成員的另一文件中的註釋, 使用 XML XPath 語法來描述你的源代碼中的類型和成員。

<list> 向XML註釋文檔中插入一個列表

<para> 向XML註釋文檔中插入一個段落

<param> 描述一個參數

<paramref> 提供了一種指示一個詞爲參數的方法

<permission> 允許你將成員的訪問許可加入到文檔中

<remarks> 用於添加有關某個類型的信息

<returns> 描述返回值

<see> 指定鏈接

<seealso> 指定希望在“請參見”一節中出現的文本

<summary> 類型或類型成員的通用描述

<value> 描述屬性

 

=============================================================

<Summary> 對整體進行概要性描述

<summary>Description</summary>
類、屬性（不推薦）、方法等

<para> 跟在Summary之後，對方法所涉及的入口參數進行有效的解釋
<param name=username>本參數是用戶的帳號</param>
方法的入口參數;

<returns> 對方法的返回值進行解釋;
<returns>返回值零代表操作成功，-1代表操作不成功</returns>
方法的返回值;

<remarks> 對一些語句進行備註性描述
<remarks>本類需要調用另外一個User類相關方法</remarks>
類、方法、屬性等;

<see> 在生成的文檔中產生一個連接到其它描述的超鏈接;
<see cref=”[member]”/>
可以在其它註釋標識符中加入

<seealso> 與上者的區別是本標識符顯示超鏈接在一個文檔的尾部的“See Also”區域，而前者在文檔之中;
<seealso cref=”[member]”/>
不可以在其它註釋標識符中加入

<value> 對一個屬性進行概要性解釋;
<value>這是一個public屬性</value>
屬性

<code> 如果需要置入一部分源代碼段，可以使用本標識符將其標記出來
<code>
public int add(int a,b)
{return a+b;
}
</code>
可以在其它註釋標識符中加入

<exception> 對程序中可能拋出的異常做解釋;
<exception cref=”System.Exception”>拋出的異常情況</exception>
在方法當中如果有拋出異常，如“try…catch結構”時可以使用本標識符做解釋

<permission> 對方法的訪問權限做一些解釋：
<permission cref=”System.Security.PermissionSet”>這是公共方法</permission>
方法，屬性

<c> 與<code>標識符基本相同，但本標識符僅用於單行代碼;
<c>return a+b;</c>
可以在其它標識符中插入使用;

<example> 舉例說明，通常與<code>配套使用;
<example> 以下示例說明如何調用Add方法:
<code>
class MyClass
{
  public static int Main()
{
return Add(1+2);
}
}
</code>
</example>
可以在其它標識符中插入;

<paramref> 在其它地方引用一個入口參數
<paramref cref=”a”>請注意，這是一個整型參數</paramref>