Einfügen von XML-Kommentaren für die Generierung der Dokumentation

In diesem Artikel wird beschrieben, wie Visual Studio Sie dabei unterstützt, Codeelemente wie z.B. Klassen und Methoden zu dokumentieren, indem es automatisch die Standardstruktur für XML-Dokumentationskommentare generiert. Sie können eine XML-Datei zur Kompilierzeit erstellen, die die Dokumentationskommentare enthält.

Sie können die vom Compiler generierte XML-Datei zusammen mit Ihrer .NET-Assembly verteilen, damit Visual Studio und andere IDEs mit IntelliSense QuickInfos über Typen und Member anzeigen können. Sie können die XML-Datei auch mithilfe von Tools wie DocFX und Sandcastle ausführen, um API-Verweiswebsites zu generieren.

Hinweis

Der Befehl Kommentar einfügen zur automatischen Einfügung einer XML-Dokumentationskommentarstruktur ist in C# und Visual Basic verfügbar. In C++ können Sie XML-Dokumentationskommentare manuell einfügen und weiterhin XML-Dokumentationsdateien zur Kompilierzeit generieren.

Aktivieren der Dokumentationsgenerierung

Aktivieren Sie zum Aktivieren der Dokumentationsgenerierung auf der Registerkarte Build>Ausgabe Ihrer Projekteigenschaften das Kontrollkästchen Hiermit generieren Sie eine Datei mit API-Dokumentation.

Standardmäßig wird eine Dokumentationsdatei, deren Name mit dem der Assembly mit einer Dateierweiterung .xml identisch ist, im selben Verzeichnis wie die Assembly generiert. Wenn Sie einen nicht standardmäßigen Namen oder Speicherort für die Datei konfigurieren möchten, geben Sie unter Pfad der XML-Dokumentationsdatei einen alternativen Speicherort ein, oder navigieren Sie zu diesem.

Alternativ können Sie die Eigenschaften GenerateDocumentationFile oder DocumentationFile Ihrer CSPROJ-, VBPROJ- oder FSPROJ-Datei hinzufügen. Legen Sie GenerateDocumentationFile auf true fest, um eine Dokumentationsdatei mit dem Standardnamen und -Speicherort zu generieren. Verwenden Sie die DocumentationFile-Eigenschaft, um einen anderen Namen oder Speicherort anzugeben.

Wenn Sie DocumentationFile allein oder mit der GenerateDocumentationFile-Eigenschaft auf true festgelegt verwenden, wird eine Dokumentationsdatei mit dem angegebenen Namen und Speicherort generiert. Wenn Sie jedoch GenerateDocumentationFile auf false festlegen, wird keine Dokumentationsdatei generiert, auch wenn Sie die DocumentationFile-Eigenschaft festlegen.

Aktivieren der Tastenkombination zum Einfügen von Kommentaren

Sie können die Option Kommentare so festlegen, dass automatisch XML-Kommentarstrukturen nach der Eingabe von /// in C# bzw. ''' in Visual Basic eingefügt werden.

1. Wählen Sie in der Menüleiste von Visual Studio Extras>Optionen aus.
2. Navigieren Sie im Dialogfeld Optionen zu Text-Editor>C# (oder Visual Basic) >Erweitert.
3. Aktivieren oder deaktivieren Sie im Abschnitt Kommentare die Option XML-Dokumentationskommentare generieren für \\\ (oder "'").

Automatisches Einfügen eines XML-Kommentars

1. Platzieren Sie in Visual Studio den Textcursor oberhalb des zu dokumentierenden Elements, z.B. einer Methode.

2. Führen Sie eine der folgenden Aktionen aus:

   • Wenn die automatische Kommentareinfügungsverknüpfung aktiviert ist, geben Sie /// in C# oder ''' in Visual Basic ein.
   • Wählen Sie im Menü Bearbeiten die Option IntelliSense>Kommentar einfügen aus.
   • Wählen Sie nach einem Rechtsklick bzw. im Kontextmenü Ausschnitt>Kommentar einfügen.

   Die XML-Kommentarstruktur wird sofort über dem Codeelement generiert. Wenn Sie zum Beispiel die folgendeGetUserName-Methode kommentieren, werden von der Vorlage das <summary>-Element, ein <param>-Element für den Parameter und ein <returns>-Element generiert, um den Rückgabewert zu dokumentieren.

   /// <summary>
   /// 
   /// </summary>
   /// <param name="id"></param>
   /// <returns></returns>
   public string GetUserName(int id)
   {
       return "username";
   }
   

   ''' <summary>
   ''' 
   ''' </summary>
   ''' <param name="id"></param>
   ''' <returns></returns>
   Public Function GetUserName(id As Integer) As String
       Return "username"
   End Function
   

3. Geben Sie Beschreibungen für jedes XML-Element an, um den Code vollständig zu dokumentieren. Zum Beispiel:

    /// <summary>
    /// Gets the username associated with the specified ID.
    /// </summary>
    /// <param name="id">The unique user ID.</param>
    /// <returns>A string containing the username for the specified ID.</returns>
    public string GetUserName(int id)
    {
        return "username";
    }
   

Sie können in Kommentaren XML-Elemente und Stile verwenden, die beim Zeigen auf das Element in der QuickInfo gerendert werden. Diese Elemente umfassen Kursiv- oder Fettformatvorlagen, Aufzählungen oder nummerierte Listen sowie klickbare cref- oder href-Links.

Geben Sie beispielsweise den folgenden Code in eine C#-Programmdatei ein:

/// <summary>
/// There are two <see href="https://bing.com">params</see>.
/// <list type="number">
/// <item><param name="id">The user <em>id</em></param></item>
/// <item><param name="username">The user <em>name</em></param></item>
/// </list>
/// </summary>
/// <returns>The <strong>username</strong>.</returns>
public static string GetUserName(int id)
{
    return "username";
}

Wenn Sie mit dem Mauszeiger auf GetUserName zeigen, wird der QuickInfo-Bereich wie folgt angezeigt:

Zugehöriger Inhalt

• Documentation comments (Dokumentationskommentare)
• XML-Dokumentation in Visual Basic
• Kommentare (C++)
• XML-Dokumentation (Visual C++)
• Codegenerierung