C# 程序員參考--XML 文檔教程

本教程展示如何使用 XML 將代碼存檔。

教程

C# 提供一種機制，供開發人員使用 XML 將其代碼存檔。在源代碼文件中，以下代碼行可以作為注釋處理并放在文件中：以 /// 開始的行；在用戶定義的類型（如類、委托或接口）、某成員（如字段、事件、屬性或方法）或某命名空間聲明之前的行。

示例

下面的示例提供對某個已存檔的類型的基本概述。若要編譯該示例，請鍵入以下命令行：

csc XMLsample.cs /doc:XMLsample.xml

這將創建 XML 文件 XMLsample.xml，您可以在瀏覽器中或使用 TYPE 命令查看該文件。

// XMLsample.cs// compile with: /doc:XMLsample.xmlusing 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 內的“智能感知”使用，用來顯示類型或成員的其他相關信息。

示例輸出

以下是從上面的類生成的 XML 文件：

<?xml version="1.0"?><doc>    <assembly>        <name>xmlsample</name>    </assembly>    <members>        <member name="T:SomeClass">            <summary>            Class level summary documentation goes here.</summary>            <remarks>            Longer comments can be associated with a type or member             through the remarks tag</remarks>        </member>        <member name="F:SomeClass.myName">            <summary>            Store for the name property</summary>        </member>        <member name="M:SomeClass.#ctor">            <summary>The class constructor.</summary>         </member>        <member name="M:SomeClass.SomeMethod(System.String)">            <summary>            Description for SomeMethod.</summary>            <param name="s"> Parameter description for s goes here</param>            <seealso cref="T:System.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>        </member>        <member name="M:SomeClass.SomeOtherMethod">            <summary>            Some other method. </summary>            <returns>            Return results are described through the returns tag.</returns>            <seealso cref="M:SomeClass.SomeMethod(System.String)">            Notice the use of the cref attribute to reference a specific method </seealso>        </member>        <member name="M:SomeClass.Main(System.String[])">            <summary>            The entry point for the application.            </summary>            <param name="args"> A list of command line arguments</param>        </member>        <member name="P:SomeClass.Name">            <summary>            Name property </summary>            <value>            A value tag is used to describe the property value</value>        </member>    </members></doc>

注意   XML 文件并不提供有關類型和成員的完整信息（例如，它不包含任何類型信息）。若要獲得有關類型或成員的完整信息，文檔文件必須與實際類型或成員上的反射一起使用。

原文轉自：http://www.kjueaiud.com