C#註釋及說明

作了這麼多年的C#開發，針對它的完整註釋都沒有好好的瞭解過，有點悲哀啊~

下面是轉載的C# 註釋及說明文章

爲了使用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>

----------------------------------------------------------------------------------

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