Share via

HOW TO：使用 XML 文件功能 (C# 程式設計手冊)

  • 發行項

下列範例會提供已記載型別的基本概觀。

範例

// If compiling from the command line, compile with: /doc:YourFileName.xml

/// <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 TestClass : TestInterface
{
    /// <summary>
    /// Store for the name property.</summary>
    private string _name = null;

    /// <summary>
    /// The class constructor. </summary>
    public TestClass()
    {
        // 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 (_name == null)
            {
                throw new System.Exception("Name is null");
            }
            return _name;
        }
    }

    /// <summary>
    /// Description for SomeMethod.</summary>
    /// <param name="s"> Parameter description for s goes here.</param>
    /// <seealso cref="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>
    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;
    }

    public int InterfaceMethod(int n)
    {
        return n * n;
    }

    /// <summary>
    /// The entry point for the application.
    /// </summary>
    /// <param name="args"> A list of command line arguments.</param>
    static int Main(System.String[] args)
    {
        // TODO: Add code to start application here.
        return 0;
    }
}

/// <summary>
/// Documentation that describes the interface goes here.
/// </summary>
/// <remarks>
/// Details about the interface go here.
/// </remarks>
interface TestInterface
{
    /// <summary>
    /// Documentation that describes the method goes here.
    /// </summary>
    /// <param name="n">
    /// Parameter n requires an integer argument.
    /// </param>
    /// <returns>
    /// The method returns an integer.
    /// </returns>
    int InterfaceMethod(int n);
}

編譯程式碼

若要編譯範例，請鍵入下列命令列：

csc XMLsample.cs /doc:XMLsample.xml

這樣會建立 XML 檔 XMLsample.xml，您可以檢視您的瀏覽器中或使用 [類型] 指令。

穩固程式設計

以 /// 起始的 XML 文件。 當您建立新的專案時，精靈會為您放置一些起始 / / 行。 處理這些註解有一些限制：

  • 文件必須依照語式正確 (Well-Formed) XML 格式。 如果 XML 不是語式正確的會產生一個警告，而且文件檔將包含註解指出發現錯誤。

  • 開發者可以自由建立自己的標記集合。 還有一組建議的標記 (請參閱進一步閱讀 ＞ 章節)。 某些建議的標記有特殊的意義：

    • <param> 標記是用來描述參數。 如果使用，編譯器會驗證該參數及所有描述於文件中的參數是否存在。 如果驗證失敗，編譯器會發出警告。

    • cref 屬性 (Attribute) 可以附加到任一個標記上，以提供程式碼項目的參考。 編譯器會驗證此程式碼項目存在。 如果驗證失敗，編譯器會發出警告。 當尋找在 cref 屬性上描述的型別時，編譯器會遵循任何 using 陳述式的指示。

    • <summary> 標記是供 Visual Studio 內部的 IntelliSense 使用，以顯示型別或成員的額外資訊。

      注意事項注意事項

      XML 檔案並不提供型別和成員的完整資訊 (例如，不包含任何型別資訊)。如需型別或成員的完整資訊，文件檔必須配合實際型別或成員上的反應來使用。

請參閱

參考

/doc (C# 編譯器選項)

XML 文件註解 (C# 程式設計手冊)

概念

C# 程式設計手冊