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

Visual Studio unterstützt Sie dabei, 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. Wählen Sie zum Aktivieren dieser Option auf der Registerkarte Build>Ausgabe Ihrer Projekteigenschaften die Option Hiermit generieren Sie eine Datei mit API-Dokumentation. aus.

Tipp

Wenn Sie einen nicht standardmäßigen Namen und Speicherort für die Dokumentationsdatei konfigurieren möchten, fügen Sie Ihrer CSPROJ- , VBPROJ- oder FSPROJ-Datei die Eigenschaft DocumentationFile hinzu.

Die vom Compiler generierte XML-Datei kann zusammen mit Ihrer .NET-Assembly verteilt werden, damit Visual Studio und andere IDEs mit IntelliSense QuickInfos über Typen und Member anzeigen können. Darüber hinaus kann die XML-Datei mithilfe von Tools wie DocFX und Sandcastle ausgeführt werden, um API-Verweiswebsites zu generieren.

Hinweis

Der Befehl Kommentar einfügen, der automatisch XML-Dokumentationskommentare einfügt, ist in C# und Visual Basic verfügbar. Dennoch können Sie XML-Dokumentationskommentare in C++-Dateien manuell einfügen, und weiterhin XML-Dokumentationskommentare zur Kompilierzeit generieren.

Einfügen von XML-Kommentaren für ein Codeelement

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

  2. Führen Sie eines der folgenden Verfahren aus:

    • Geben Sie /// in C# oder ''' in Visual Basic ein

    • Wählen Sie im Menü BearbeitenIntelliSense>Kommentar einfügen aus.

    • Führen Sie einen Rechtsklick aus, bzw. nutzen Sie das Kontextmenü, und klicken dann auf Ausschnitt>Kommentar einfügen.

    Die XML-Vorlage wird sofort über dem Codeelement generiert. Wenn Sie zum Beispiel eine Methode kommentieren, wird ein <Summary>-Element, ein <param>-Element für jeden Parameter und ein <returns>-Element generiert, um den Rückgabewert zu dokumentieren.

    XML comment template - C#

    XML comment template - Visual Basic

  3. Geben Sie Beschreibungen für jedes XML-Element an, um das Codeelement vollständig zu dokumentieren.

    Screenshot showing the completed comment.

Sie können in XML-Kommentaren Stile verwenden, die beim Zeigen auf das Element in der QuickInfo gerendert werden. Zu diesen Stilen zählen z. B. die Kursiv- oder Fettformatierung, Aufzählungslisten und klickbare Links.

Screenshot showing the completed comment with style tags for italics, bold, bullets, and a clickable link.

Hinweis

Es gibt eine Option zum Ein- und Ausblenden von XML-Dokumentationskommentaren nach der Eingabe von /// in C# oder ''' in Visual Basic. Wählen Sie in der Menüleiste Extras>Optionen aus, um das Dialogfeld Optionen zu öffnen. Navigieren Sie dann zu Text-Editor>C# (oder Visual Basic) >Erweitert. Suchen Sie im Abschnitt Editor-Hilfe nach der Option XML-Dokumentationskommentare generieren.

Weitere Informationen