為自己的類添加說明文字 - 中國WEB開發者網絡 (http://www.webasp.net) -- 技術教程 (http://www.webasp.net/article/) --- 為自己的類添加說明文字 (http://www.webasp.net/article/18/17021.htm)

-- 作者：未知 -- 發佈日期： 2005-03-16

教程 C# 提供一種機制，供開發人員使用 XML 將其代碼存檔。在源代碼文件中，以下代碼行可以作為註釋處理並放在文件中：以 /// 開始的行；在用戶定義的類型（如類、委託或接口）、某成員（如字段、事件、屬性或方法）或某命名空間聲明之前的行。 示例 下面的示例提供對某個已存檔的類型的基本概述。若要編譯該示例，請鍵入以下命令行： csc XMLsample.cs /doc:XMLsample.xml 這將創建 XML 文件 XMLsample.xml，您可以在瀏覽器中或使用 TYPE 命令查看該文件。 // XMLsample.cs // compile with: /doc:XMLsample.xml using System; /// <summary> /// Class level summary documentation goes here.</summary> /// <remarks> /// Longer comments can be associated with a type or member /// through the remarks tag</remarks> public class SomeClass { /// <summary> /// Store for the name property</summary> private string myName = null; /// <summary> /// The class constructor. </summary> public SomeClass() { // TODO: Add Constructor Logic here } /// <summary> /// Name property </summary> /// <value> /// A value tag is used to describe the property value</value> public string Name { get { if ( myName == null ) { throw new Exception("Name is null"); } return myName; } } /// <summary> /// Description for SomeMethod.</summary> /// <param name="s"> Parameter description for s goes here</param> /// <seealso cref="String"> /// You can use the cref attribute on any tag to reference a type or member /// and the compiler will check that the reference exists. </seealso> public void SomeMethod(string s) { } /// <summary> /// Some other method. </summary> /// <returns> /// Return results are described through the returns tag.</returns> /// <seealso cref="SomeMethod(string)"> /// Notice the use of the cref attribute to reference a specific method </seealso> public int SomeOtherMethod() { return 0; } /// <summary> /// The entry point for the application. /// </summary> /// <param name="args"> A list of command line arguments</param> public static int Main(String[] args) { // TODO: Add code to start application here return 0; } } 代碼討論 XML 文檔以 /// 開頭。創建新項目時，嚮導將為您放入一些起始 /// 行。對這些註釋的處理有一些限制： 文檔必須是符合標準格式的 XML。如果 XML 不符合標準格式，將生成警告，並且文檔文件將包含一條註釋，指出遇到錯誤。有關符合標準格式的 XML 的更多信息，請參見 XML 詞彙表。 開發人員可自由創建自己的標記集。有一套建議的標記（請參見「其他閱讀材料」部分）。某些建議的標記具有特殊含義： <param> 標記用於描述參數。如果使用，編譯器將驗證參數是否存在，以及文檔中是否描述了所有參數。如果驗證失敗，則編譯器發出警告。 cref 屬性可以附加到任意標記，以提供對代碼元素的引用。編譯器將驗證該代碼元素是否存在。如果驗證失敗，則編譯器發出警告。查找 cref 屬性中描述的類型時，編譯器還考慮任何 using 語句。 <summary> 標記由 Visual Studio 內的「智能感知」使用，用來顯示類型或成員的其他相關信息。 在 Visual Studio 開發環境中設置此編譯器選項 若要將生成的 .xml 文件用於智能感知功能，請使該 .xml 文件的文件名與要支持的程序集同名，然後確保該 .xml 文件放入與該程序集相同的目錄中。這樣，在 Visual Studio 項目中引用程序集時，也可找到該 .xml 文件。 單擊「配置屬性」文件夾。 單擊「生成」屬性頁。 修改「XML 文檔文件」屬性。 <summary></summary> 描述類型成員。 <remarks></remarks> 指定類或其他類型的概述信息。 <param></param> 在方法聲明的註釋中使用以描述該方法的一個參數。 <returns></returns> 在方法聲明的註釋中使用以描述返回值。 <newpara></newpara> 在註釋中開始一個新段落。

webasp.net