C# Language
XML-Dokumentationskommentare

Bemerkungen

Einfache Methodenanmerkung

Dokumentationskommentare werden direkt über der von ihnen beschriebenen Methode oder Klasse platziert. Sie beginnen mit drei Schrägstrichen /// und ermöglichen die Speicherung von Metainformationen über XML.

/// <summary>
/// Bar method description
/// </summary>
public void Bar()
{ 
        
}

Informationen in den Tags können von Visual Studio und anderen Tools verwendet werden, um Dienste wie IntelliSense bereitzustellen:

Siehe auch die Liste der üblichen Dokumentations-Tags von Microsoft .

Kommentare zur Schnittstellen- und Klassendokumentation

/// <summary>
/// This interface can do Foo
/// </summary>
public interface ICanDoFoo
{
    // ... 
}

/// <summary>
/// This Bar class implements ICanDoFoo interface
/// </summary>
public class Bar : ICanDoFoo
{
    // ...
}

Ergebnis

Zusammenfassung der Benutzeroberfläche

Klassenzusammenfassung

Methodendokumentationskommentar mit Parametern und gibt Elemente zurück

/// <summary>
/// Returns the data for the specified ID and timestamp.
/// </summary>
/// <param name="id">The ID for which to get data. </param>
/// <param name="time">The DateTime for which to get data. </param>
/// <returns>A DataClass instance with the result. </returns>
public DataClass GetData(int id, DateTime time)
{
   // ...
}

IntelliSense zeigt Ihnen die Beschreibung für jeden Parameter an:

Tipp: Wenn Intellisense in Visual Studio nicht angezeigt wird, löschen Sie die erste Klammer oder das erste Komma und geben Sie es erneut ein.

Generieren von XML aus Dokumentationskommentaren

Verwenden Sie zum Generieren einer XML-Dokumentationsdatei aus Dokumentationskommentaren im Code die Option /doc mit dem C # -Compiler csc.exe .

Aktivieren Sie in Visual Studio 2013/2015 unter Projekt -> Eigenschaften -> Erstellen -> Ausgabe das Kontrollkästchen XML documentation file :

Beim Erstellen des Projekts wird vom Compiler eine XML-Datei mit einem Namen erstellt, der dem Projektnamen entspricht (z. B. XMLDocumentation.dll -> XMLDocumentation.xml ).

Wenn Sie die Assembly in einem anderen Projekt verwenden, stellen Sie sicher, dass sich die XML-Datei in demselben Verzeichnis befindet wie die DLL, auf die verwiesen wird.

Dieses Beispiel:

/// <summary>
/// Data class description
/// </summary>
public class DataClass
{
    /// <summary>
    /// Name property description
    /// </summary>
    public string Name { get; set; }
}


/// <summary>
/// Foo function
/// </summary>
public class Foo
{
    /// <summary>
    /// This method returning some data
    /// </summary>
    /// <param name="id">Id parameter</param>
    /// <param name="time">Time parameter</param>
    /// <returns>Data will be returned</returns>
    public DataClass GetData(int id, DateTime time)
    {
        return new DataClass();
    }
}

Erzeugt diese XML-Datei beim Build:

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>XMLDocumentation</name>
    </assembly>
    <members>
        <member name="T:XMLDocumentation.DataClass">
            <summary>
            Data class description
            </summary>
        </member>
        <member name="P:XMLDocumentation.DataClass.Name">
            <summary>
            Name property description
            </summary>
        </member>
        <member name="T:XMLDocumentation.Foo">
            <summary>
            Foo function
            </summary>
        </member>
        <member name="M:XMLDocumentation.Foo.GetData(System.Int32,System.DateTime)">
            <summary>
            This method returning some data
            </summary>
            <param name="id">Id parameter</param>
            <param name="time">Time parameter</param>
            <returns>Data will be returned</returns>
        </member>
    </members>
</doc>

Verweis auf eine andere Klasse in der Dokumentation

Das <see> -Tag kann verwendet werden, um eine Verbindung zu einer anderen Klasse herzustellen. Es enthält den cref Member, der den Namen der Klasse enthalten soll, auf die verwiesen werden soll. Visual Studio stellt beim Schreiben dieses Tags Intelligense bereit, und solche Referenzen werden auch beim Umbenennen der referenzierten Klasse verarbeitet.

/// <summary>
/// You might also want to check out <see cref="SomeOtherClass"/>.
/// </summary>
public class SomeClass
{
}

In Visual Studio Intellisense-Popups werden diese Verweise auch farbig im Text angezeigt.

Verwenden Sie zum Verweisen auf eine generische Klasse Folgendes:

/// <summary>
/// An enhanced version of <see cref="List{T}"/>.
/// </summary>
public class SomeGenericClass<T>
{
}