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

Das folgende Beispiel bietet eine grundlegende Übersicht über einen Typ, der dokumentierten 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);
}

// Diese XML-Datei wurde mit dem vorherigen Codebeispiel generiert.
<?xml version="1.0"?>
<doc>
<assembly>
<name>xmlsample</name>
</assembly>
<members>
<member name="T:SomeClass">
<summary>
Hier eine Zusammenfassung der Klassenebene dokumentieren.</summary>
<remarks>
Mit den remarks-Tags können einem Typ oder Member längere
Kommentare zugeordnet werden.</remarks>
</member>
<member name="F:SomeClass.m_Name">
<summary>
Speicher für die Name-Eigenschaft</summary>
</member>
<member name="M:SomeClass.#ctor">
<summary>Konstruktor der Klasse.</summary>
</member>
<member name="M:SomeClass.SomeMethod(System.String)">
<summary>
Beschreibung von SomeMethod.</summary>
<param name="s">Hier Beschreibung für den Parameter „s“ einfügen.</param>
<seealso cref="T:System.String">
Sie können für alle Tags das cref-Attribut verwenden, um auf einen Typ oder Member
zu verweisen. Der Compiler prüft dann, ob der Verweis vorhanden ist. </seealso>
</member>
<member name="M:SomeClass.SomeOtherMethod">
<summary>
Eine andere Methode. </summary>
<returns>
Rückgabeergebnisse werden mit returns-Tags beschrieben.</returns>
<seealso cref="M:SomeClass.SomeMethod(System.String)">
Beachten Sie die Verwendung des cref-Attributs, um auf eine bestimmte Methode zu verweisen.</seealso>
</member>
<member name="M:SomeClass.Main(System.String[])">
<summary>
Der Einstiegspunkt der Anwendung.
</summary>
<param name="args"> Eine Liste der Befehlszeilenargumente.</param>
</member>
<member name="P:SomeClass.Name">
<summary>
Name-Eigenschaft </summary>
<value>
Der Eigenschaftswert wird mit value-Tags beschrieben.</value>
</member>
</members>
</doc>

Kompilieren des Codes

Geben Sie die folgende Befehlszeile ein, um das Beispiel zu kompilieren:

csc XMLsample.cs /doc:XMLsample.xml

Dadurch wird die XML-Datei „XMLsample.xml“ erstellt, die Sie in Ihrem Browser oder mithilfe des TYPE-Befehls anzeigen können.

Stabile Programmierung

XML-Dokumentation beginnt mit ///. Wenn Sie ein neues Projekt erstellen, fügt der Assistent einige ///-Startzeilen für Sie ein. Die Verarbeitung dieser Kommentare weist einige Einschränkungen auf:

  • Die Dokumentation muss wohlgeformtes XML sein. Wenn das XML nicht wohlgeformt ist, wird eine Warnung generiert, und die Dokumentationsdatei enthält einen Kommentar, der besagt, dass ein Fehler aufgetreten ist.

  • Entwickler können ihren eigenen Satz von Tags erstellen. Es gibt ein Reihe empfohlener Tags (siehe Abschnitt „Weiterführende Themen“). Einige der empfohlenen Tags haben eine besondere Bedeutung:

    • Das <param>-Tag wird verwendet, um Parameter zu beschreiben. Wenn es verwendet wird, überprüft der Compiler, ob der Parameter vorhanden ist und dass alle Parameter in der Dokumentation beschrieben werden. Wenn 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. Wenn die Überprüfung fehlschlägt, gibt der Compiler eine Warnung aus. Der Compiler berücksichtigt alle using-Anweisungen, wenn er nach einem Typ sucht, der im cref-Attribut beschrieben wird.

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

      Hinweis

      Die XML-Datei enthält keine vollständigen Informationen über den Typ und die Member (z. B. fehlen Typinformationen). Um vollständige Informationen zu einem Typ oder Member zu erhalten, muss die Dokumentationsdatei zusammen mit Reflektion über den tatsächlichen Typ oder Member verwendet werden.

Siehe auch

C#-Programmierhandbuch
/doc (C#-Compileroptionen)
XML-Dokumentationskommentare