(0) exportieren Drucken
Alle erweitern
Dieser Artikel wurde maschinell übersetzt. Bewegen Sie den Mauszeiger über die Sätze im Artikel, um den Originaltext anzuzeigen. Weitere Informationen
Übersetzung
Original

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

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


// 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>
            An dieser Stelle steht in der Dokumentation die Zusammenfassung auf Klassenebene.</summary>
            <remarks>
            Mit dem <remarks>-Tag können einem Typ oder Member 
            tag</remarks> durch die Hinweise
        </member>
         <member name="F:SomeClass.m_Name"> 
            <summary>
            Speicher für den Namen property</summary>
        </member>
         <member name="M:SomeClass.#ctor"> 
             <summary> Die Klasse constructor.</summary> 
        </member>
         <member name="M:SomeClass.SomeMethod(System.String)"> 
            <summary>
            Beschreibung von SomeMethod.</summary>
             <param name="s"> Beschreibung der Parameter für here</param> geht s
            <seealso cref="T:System.String">
            Sie können mit dem cref-Attribut für jedes Tag auf einen Typ oder Member verweisen, 
            und der Compiler überprüft, ob der Verweis vorhanden ist.  </seealso>
        </member>
         <member name="M:SomeClass.SomeOtherMethod"> 
            <summary>
            Eine andere Methode.  </summary>
            <returns>
            Mit dem <returns>-Tag werden Rückgabeergebnisse beschrieben.</returns>
             <seealso cref="M:SomeClass.SomeMethod(System.String)"> 
            Beachten Sie die Verwendung des cref Attribut eine bestimmte Methode zu verweisen </seealso>
        </member>
         <member name="M:SomeClass.Main(System.String[])"> 
            <summary>
            Der Einstiegspunkt für die Anwendung.  </summary>
             <param name="args"> Eine Liste der Befehlszeile arguments</param>
        </member>
         <member name="P:SomeClass.Name"> 
            <summary>
            Name-Eigenschaft </summary>
            <value>
            Ein Werts tag wird verwendet, um die Eigenschaft zu beschreiben value</value>
        </member>
    </members>
</doc>  

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.

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 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.

Community-Beiträge

HINZUFÜGEN
Anzeigen:
© 2014 Microsoft