文件標籤的分隔符號 (C# 程式設計手冊)
更新:2007 年 11 月
使用 XML 文件註解時會需要分隔符號,讓編譯器知道文件註解從何處開始和結束。您可以使用下列幾種分隔符號,以搭配 XML 文件標記使用:
///
這是顯示在文件範例中並且為 Visual C# 專案範本所使用的形式。注意事項: Visual Studio IDE 提供一種稱為智慧型註解編輯的功能,當您在程式碼編輯器中輸入 /// 分隔符號之後,會自動插入 <summary> 和 </summary> 標記,並將游標移到這兩個標記之間。請從專案屬性頁中的選項對話方塊、文字編輯器、C#、格式存取這項功能。
/** */
多行分隔符號。
使用 /** */ 分隔符號的格式化規則:
對於包含 /** 分隔符號的程式碼行來說,該行的其餘部分若是泛空白字元,就不會以註解方式處理。但若第一個字元是泛空白字元,該字元就會被忽略,並處理該程式碼行的其他內容。否則,在 /** 分隔符號之後的所有內容,都會當做註解的一部分來處理。
對包含 */ 分隔符號的程式碼行來說,如果 */ 分隔符號之前只有泛空白字元,該行就會被忽略。否則,在 */ 分隔符號之前,程式碼行的文字將會當做註解的一部分來處理,並受制於下列項目符號中所描述的模式比對規則。
對開頭為 /** 分隔符號程式碼行之後的程式碼,編譯器會尋找每一行程式碼開頭,查看其是否包含選擇性泛空白字元加上星號 (*),再緊接著更多選擇性泛空白字元所組成的共通模式。如果編譯器在每一行開頭找到共通的字元組合時,則編譯器會忽略從 /** 到 */之間 (含該行) 的所有程式碼行的此種模式。
以下是部分範例:
下列註解中唯一會進行處理的部分,是以 <summary> 開頭的那行程式碼。下列兩種標記格式會產生相同的註解:
/**
<summary>text</summary>
*/
/** <summary>text</summary> */
編譯器會在第二行與第三行程式碼的開頭套用 " * " 的模式以忽略該行。
/**
* <summary>
* text </summary>*/
編譯器在此註解中找不出任何模式,因為第二行程式碼並沒有出現星號。因此,第二行和第三行程式碼中的所有文字,往上直到 */ 之間,將會當做註解的一部分來處理。
/**
* <summary>
text </summary>*/
因為兩種原因的影響,編譯器無法在此註解中找到任何模式。首先,因為沒有程式碼行開始於在星號之前,就先包含了固定數目的空白字元。其次,第五行程式碼以標籤做為開頭,與空白字元不相符。因此,從第二行程式碼到 */ 之間的所有文字,都會當做註解的一部分來處理。
/**
* <summary>
* text
* text2
* </summary>
*/