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

Im folgenden Beispiel wird eine grundlegende Übersicht über eines Typs, der dokumentiert wurde.

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

Kompilieren des Codes

Zum Kompilieren des Beispiels geben Sie die folgende Befehlszeile ein:

csc XMLsample.cs /doc:XMLsample.xml

Dadurch wird die XML-Datei XMLsample.xml, die Sie anzeigen können oder indem Sie im Browser den TYPE-Befehl verwenden.

Robuste Programmierung

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

• Die Dokumentation muss regelkonformes XML aufweisen.Wenn das XML nicht wohl geformt ist, wird eine Warnung ausgegeben, und die Dokumentationsdatei enthält einen Kommentar, der besagt, dass ein Fehler aufgetreten ist.

• Der Entwickler kann auch eigene Tagsets entwickeln.Es gibt eine Reihe empfohlener Tags (finden Sie weiterführende Literatur-Abschnitt).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 enthält keine genauen Informationen über den Typ und die Member enthält (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

Referenz

/doc (C#-Compileroptionen)

XML-Dokumentationskommentare (C#-Programmierhandbuch)

Konzepte

C#-Programmierhandbuch