Gewusst wie: Verwenden der XML-Dokumentationsfeatures (C#-Programmierhandbuch)

Aktualisiert: November 2007

Das folgende Beispiel bietet eine allgemeine Übersicht über einen dokumentierten Typ.

Beispiel

// compile with: /doc:DocFileName.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
{
    /// <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;
    }

    /// <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;
    }
}

// This .xml file was generated with the previous code sample.
<?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.m_Name">
            <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>

Kompilieren des Codes

Sie kompilieren das Beispiel, indem Sie folgende Befehlszeile eingeben:

csc XMLsample.cs /doc:XMLsample.xml

Daraufhin wird die XML-Datei XMLsample.xml erstellt, die Sie in einem Browser oder mithilfe des TYPE-Befehls anzeigen lassen können.

Robuste Programmierung

Die XML-Dokumentation beginnt mit drei Schrägstrichen (///). Wenn Sie ein neues Projekt erstellen, fügt der Assistent einige Startzeilen (///) für Sie ein. Die Verarbeitung dieser Kommentare unterliegt einigen Beschränkungen:

• Die Dokumentation muss regelkonformes XML aufweisen. Falls das XML-Format nicht regelkonform ist, wird eine Warnung ausgegeben und ein Kommentar in die Dokumentation eingefügt, dass ein Fehler aufgetreten ist.

• Der Entwickler kann auch eigene Tagsets entwickeln. Es gibt ein empfohlenes Tagset (siehe Abschnitt "Weitere Themen"). Einige der empfohlenen Tags haben eine besondere Bedeutung:

  • Das <param>-Tag wird zur Beschreibung von Parametern verwendet. Bei Verwendung dieses Tags stellt der Compiler sicher, dass der Parameter vorhanden ist und dass alle Parameter in der Dokumentation beschrieben werden. Falls die Überprüfung fehlschlägt, gibt der Compiler eine Warnung aus.

  • Das cref-Attribut kann an jedes Tag angefügt werden, um einen Verweis auf ein Codeelement bereitzustellen. Der Compiler überprüft, ob dieses Codeelement vorhanden ist. Falls die Überprüfung fehlschlägt, gibt der Compiler eine Warnung aus. Bei der Suche nach einem im cref-Attribut beschriebenen Typ beachtet der Compiler etwaige using-Anweisungen.

  • Das <summary>-Tag wird innerhalb von Visual Studio von IntelliSense verwendet, um zusätzliche Informationen über einen Typ oder einen Member anzuzeigen.

    Hinweis:
    Die XML-Datei liefert keine vollständigen Informationen zu Typen und Membern (sie umfasst z. B. keine Typinformationen). Um vollständige Informationen zu einem Typ oder Member zu erhalten, muss die Dokumentationsdatei in Verbindung mit der Reflektion des aktuellen Typs oder Members verwendet werden.

Siehe auch

Aufgaben

Beispiel für die XML-Dokumentation

Konzepte

C#-Programmierhandbuch

Referenz

/doc (Dokumentationskommentare verarbeiten) (C#-Compileroptionen)

XML-Dokumentationskommentare (C#-Programmierhandbuch)