C# 注釋文法

注釋文法

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

預定義的標籤            用處 <c>                             將說明中的文本標記為代碼 <code>                       提供了一種將多行指示為代碼的方法 <example>                  指定使用方法或其他庫成員的樣本 <exception>         允許你指定可能發生的異常類 <include>                           允許你引用描述原始碼中類型和成員的另一檔案中的注釋, 使用 XML XPath 文法來描述你的原始碼中的類型和成員。 <list>                           向XML注釋文檔中插入一個列表 <para>                        向XML注釋文檔中插入一個段落 <param>                     描述一個參數 <paramref>                 提供了一種指示一個詞為參數的方法 <permission>              允許你將成員的訪問許可加入到文檔中 <remarks>                  用於添加有關某個類型的資訊 <returns>                    描述傳回值 <see>                         指定連結 <seealso>                   指定希望在“請參見”一節中出現的文本 <summary>                 類型或類型成員的通用描述 <value>                描述屬性

例子

下面的例子為我們常見的HelloWorld控制台應用程式添加註釋：

using System; namespace HelloWorld {     /// <summary>     /// Sample Hello World in C#     /// </summary>     public class HelloWorld     {         /// <summary>         /// Console Application Entry Point         /// <param name="args">Command Line Arguments</param>         /// <returns>Status code of 0 on successful run</returns>         /// </summary>         public static int Main(string[] args)         {             System.Console.WriteLine("HelloWorld");             string name = System.Console.ReadLine();             return(0);         }     } }

為產生XML注釋文檔，我們在調用csc編譯原始碼時使用/doc選項：

csc /doc:HelloWorld.xml helloworld.cs

       產生的結果文檔如下：

<?xml version="1.0"?> <doc>     <assembly>         <name>XMlComment</name>     </assembly>     <members>         <member name="T:HelloWorld.HelloWorld">             <summary>             Sample Hello World in C#             </summary>         </member>         <member name="M:HelloWorld.HelloWorld.Main(System.String[])">             <summary>             Console Application Entry Point             <param name="args">Command Line Arguments</param>             <returns>Status code of 0 on successful run</returns>             </summary>         </member>     </members> </doc>

 

HTML頁面 www.elivn.com

你可能會問自己：我應該如何才能得到具有良好格式的HTML頁面呢？很簡單，你可以編寫自己的XSL來轉換產生的XML注釋文檔，或者使用Visual Studio.NET開發工具。通過使用VS.NET的【工具】菜單中的【產生注釋web頁】，你可以得到一系列詳細說明你的項目或解決方案的HTML頁面。下面就是通過VS.NET產生的注釋helloWorld程式的HTML頁面快照：

注釋文法

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

預定義的標籤            用處 <c>                             將說明中的文本標記為代碼 <code>                       提供了一種將多行指示為代碼的方法 <example>                  指定使用方法或其他庫成員的樣本 <exception>         允許你指定可能發生的異常類 <include>                           允許你引用描述原始碼中類型和成員的另一檔案中的注釋, 使用 XML XPath 文法來描述你的原始碼中的類型和成員。 <list>                           向XML注釋文檔中插入一個列表 <para>                        向XML注釋文檔中插入一個段落 <param>                     描述一個參數 <paramref>                 提供了一種指示一個詞為參數的方法 <permission>              允許你將成員的訪問許可加入到文檔中 <remarks>                  用於添加有關某個類型的資訊 <returns>                    描述傳回值 <see>                         指定連結 <seealso>                   指定希望在“請參見”一節中出現的文本 <summary>                 類型或類型成員的通用描述 <value>                描述屬性

例子

下面的例子為我們常見的HelloWorld控制台應用程式添加註釋：

using System; namespace HelloWorld {     /// <summary>     /// Sample Hello World in C#     /// </summary>     public class HelloWorld     {         /// <summary>         /// Console Application Entry Point         /// <param name="args">Command Line Arguments</param>         /// <returns>Status code of 0 on successful run</returns>         /// </summary>         public static int Main(string[] args)         {             System.Console.WriteLine("HelloWorld");             string name = System.Console.ReadLine();             return(0);         }     } }

為產生XML注釋文檔，我們在調用csc編譯原始碼時使用/doc選項：

csc /doc:HelloWorld.xml helloworld.cs

       產生的結果文檔如下：

<?xml version="1.0"?> <doc>     <assembly>         <name>XMlComment</name>     </assembly>     <members>         <member name="T:HelloWorld.HelloWorld">             <summary>             Sample Hello World in C#             </summary>         </member>         <member name="M:HelloWorld.HelloWorld.Main(System.String[])">             <summary>             Console Application Entry Point             <param name="args">Command Line Arguments</param>             <returns>Status code of 0 on successful run</returns>             </summary>         </member>     </members> </doc>

 

HTML頁面 www.elivn.com

你可能會問自己：我應該如何才能得到具有良好格式的HTML頁面呢？很簡單，你可以編寫自己的XSL來轉換產生的XML注釋文檔，或者使用Visual Studio.NET開發工具。通過使用VS.NET的【工具】菜單中的【產生注釋web頁】，你可以得到一系列詳細說明你的項目或解決方案的HTML頁面。下面就是通過VS.NET產生的注釋helloWorld程式的HTML頁面快照：