Gewusst wie: Verwenden der XML-Dokumentationsfunktionen (C#-Programmierhandbuch)How to: Use the XML Documentation Features (C# Programming Guide)

Das folgende Beispiel bietet eine grundlegende Übersicht über einen Typ, der dokumentierten wurde.The following sample provides a basic overview of a type that has been documented.

BeispielExample

// 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.// This .xml file was generated with the previous code sample.
<?xml version="1.0"?><?xml version="1.0"?>
<doc><doc>
<assembly><assembly>
<name>xmlsample</name><name>xmlsample</name>
</assembly></assembly>
<members><members>
<member name="T:SomeClass"><member name="T:SomeClass">
<summary><summary>
Hier eine Zusammenfassung der Klassenebene dokumentieren.</summary>Class level summary documentation goes here.</summary>
<remarks><remarks>
Längere Kommentare können einen Typ oder Member zugeordnet werden.Longer comments can be associated with a type or member
Kommentare zugeordnet werden.</remarks>through the remarks tag</remarks>
</member></member>
<member name="F:SomeClass.m_Name"><member name="F:SomeClass.m_Name">
<summary><summary>
Speicher für die Name-Eigenschaft</summary>Store for the name property</summary>
</member></member>
<member name="M:SomeClass.#ctor"><member name="M:SomeClass.#ctor">
<Zusammenfassung > Klassenkonstruktor. < /summary ><summary>The class constructor.</summary>
</member></member>
<member name="M:SomeClass.SomeMethod(System.String)"><member name="M:SomeClass.SomeMethod(System.String)">
<summary><summary>
Beschreibung von SomeMethod.</summary>Description for SomeMethod.</summary>
<param name="s">Hier Beschreibung für den Parameter „s“ einfügen.</param><param name="s"> Parameter description for s goes here</param>
<seealso cref="T:System.String"><seealso cref="T:System.String">
Sie können auf einem beliebigen Tag Cref-Attribut verwenden, auf einen Typ oder Member verweisenYou can use the cref attribute on any tag to reference a type or member
zu verweisen. Der Compiler prüft dann, ob der Verweis vorhanden ist. </seealso>and the compiler will check that the reference exists. </seealso>
</member></member>
<member name="M:SomeClass.SomeOtherMethod"><member name="M:SomeClass.SomeOtherMethod">
<summary><summary>
Eine andere Methode. </summary>Some other method. </summary>
<returns><returns>
Rückgabeergebnisse werden mit returns-Tags beschrieben.</returns>Return results are described through the returns tag.</returns>
<seealso cref="M:SomeClass.SomeMethod(System.String)"><seealso cref="M:SomeClass.SomeMethod(System.String)">
Beachten Sie die Verwendung des cref-Attributs, um auf eine bestimmte Methode zu verweisen.</seealso>Notice the use of the cref attribute to reference a specific method </seealso>
</member></member>
<member name="M:SomeClass.Main(System.String[])"><member name="M:SomeClass.Main(System.String[])">
<summary><summary>
Der Einstiegspunkt der Anwendung.The entry point for the application.
</summary></summary>
<param name="args"> Eine Liste der Befehlszeilenargumente.</param><param name="args"> A list of command line arguments</param>
</member></member>
<member name="P:SomeClass.Name"><member name="P:SomeClass.Name">
<summary><summary>
Name-Eigenschaft </summary>Name property </summary>
<value><value>
Der Eigenschaftswert wird mit value-Tags beschrieben.</value>A value tag is used to describe the property value</value>
</member></member>
</members></members>
</doc></doc>

Kompilieren des CodesCompiling the Code

Geben Sie die folgende Befehlszeile ein, um das Beispiel zu kompilieren:To compile the example, type the following command line:

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.This will create the XML file XMLsample.xml, which you can view in your browser or by using the TYPE command.

Stabile ProgrammierungRobust Programming

XML-Dokumentation beginnt mit ///.XML documentation starts with ///. Wenn Sie ein neues Projekt erstellen, fügt der Assistent einige ///-Startzeilen für Sie ein.When you create a new project, the wizards put some starter /// lines in for you. Die Verarbeitung dieser Kommentare weist einige Einschränkungen auf:The processing of these comments has some restrictions:

  • Die Dokumentation muss wohlgeformtes XML sein.The documentation must be well-formed XML. Wenn das XML nicht wohlgeformt ist, wird eine Warnung generiert, und die Dokumentationsdatei enthält einen Kommentar, der besagt, dass ein Fehler aufgetreten ist.If the XML is not well-formed, a warning is generated and the documentation file will contain a comment that says that an error was encountered.

  • Entwickler können ihren eigenen Satz von Tags erstellen.Developers are free to create their own set of tags. Es gibt ein Reihe empfohlener Tags (siehe Abschnitt „Weiterführende Themen“).There is a recommended set of tags (see the Further Reading section). Einige der empfohlenen Tags haben eine besondere Bedeutung:Some of the recommended tags have special meanings:

    • Das <param>-Tag wird verwendet, um Parameter zu beschreiben.The <param> tag is used to describe parameters. Wenn es verwendet wird, überprüft der Compiler, ob der Parameter vorhanden ist und dass alle Parameter in der Dokumentation beschrieben werden.If used, the compiler will verify that the parameter exists and that all parameters are described in the documentation. Wenn die Überprüfung fehlschlägt, gibt der Compiler eine Warnung aus.If the verification failed, the compiler issues a warning.

    • Das cref-Attribut kann an jedes Tag angefügt werden, um einen Verweis auf ein Codeelement bereitzustellen.The cref attribute can be attached to any tag to provide a reference to a code element. Der Compiler überprüft, ob dieses Codeelement vorhanden ist.The compiler will verify that this code element exists. Wenn die Überprüfung fehlschlägt, gibt der Compiler eine Warnung aus.If the verification failed, the compiler issues a warning. Der Compiler berücksichtigt alle using-Anweisungen, wenn er nach einem Typ sucht, der im cref-Attribut beschrieben wird.The compiler respects any using statements when it looks for a type described in the cref attribute.

    • Das <summary>-Tag wird von IntelliSense in Visual Studio verwendet, um zusätzliche Informationen über einen Typ oder Member anzuzeigen.The <summary> tag is used by IntelliSense inside Visual Studio to display additional information about a type or member.

      Hinweis

      Die XML-Datei enthält keine vollständigen Informationen über den Typ und die Member (z. B. fehlen Typinformationen).The XML file does not provide full information about the type and members (for example, it does not contain any type information). 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.To get full information about a type or member, the documentation file must be used together with reflection on the actual type or member.

Siehe auchSee Also

C#-ProgrammierhandbuchC# Programming Guide
/ doc (C#-Compileroptionen)/doc (C# Compiler Options)
XML-DokumentationskommentareXML Documentation Comments