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

Aktualisiert: April 2011

Mit der XML-Dokumentation können Sie Code effizient dokumentieren. Das folgende Beispiel bietet eine elementare Übersicht.

Beispiel

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

Durch das vorangehende Beispiel wird die folgende XML-Datei generiert. Beachten Sie, dass die Kommentare aus der Schnittstellendefinition in der Klasse enthalten sind, die die Schnittstelle implementiert.

Kompilieren des Codes

Um das Beispiel zu kompilieren, können Sie die folgende Befehlszeile eingeben: csc XMLsample.cs /doc:XMLsample.xml.

Mit diesem Befehl wird die XML-Datei XMLsample.xml erstellt, die Sie in einem Browser oder einem Textverarbeitungsprogramm anzeigen können.

Alternativ können Sie im Projektmappen-Explorer mit der rechten Maustaste auf den Namen des Projekts klicken und dann auf Eigenschaften klicken. Wählen Sie auf der Registerkarte Erstellen im Abschnitt Ausgabe die Option XML-Dokumentationsdatei aus, und geben Sie dann einen Namen für die XML-Datei ein.

Robuste Programmierung

Die XML-Dokumentation beginnt mit drei Schrägstrichen (///). Wenn Sie ein neues Projekt erstellen, fügt die IDE automatisch mit drei Schrägstrichen (///) beginnende Kommentarzeilen hinzu. Die Verarbeitung dieser Kommentare unterliegt den folgenden Beschränkungen:

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

• Entwickler können eigene Sätze von Tags erstellen. Es gibt jedoch einen Satz empfohlener Tags (siehe den Abschnitt Siehe auch dieses Themas), die eine besondere Bedeutung haben, wie in den folgenden Beispielen beschrieben:

  • Das <param>-Tag wird zur Beschreibung von Parametern verwendet. Bei Verwendung dieses Tags überprüft der Compiler, ob der Parameter vorhanden ist und ob 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 das 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.

    Tipp

    Die XML-Datei enthält keine umfassenden Informationen über den Typ und die Member. Beispielsweise enthält sie 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

Referenz

/doc (C#-Compileroptionen)

XML-Dokumentationskommentare (C#-Programmierhandbuch)

Konzepte

C#-Programmierhandbuch

Änderungsprotokoll