Dokumentieren von Code mit XML (Visual Basic)

  • Artikel

In Visual Basic können Sie Ihren Code mithilfe von XML dokumentieren.

XML-Dokumentationskommentare

Visual Basic bietet eine einfache Möglichkeit zum automatischen Erstellen von XML-Dokumentationen für Projekte. Sie können automatisch eine XML-Skelett für Ihre Typen und Member generieren und dann Zusammenfassungen, beschreibende Dokumentationen für jeden Parameter und andere Hinweise bereitstellen. Mit dem entsprechenden Setup wird die XML-Dokumentation automatisch in eine XML-Datei mit demselben Stammdateinamen wie Ihr Projekt ausgegeben. Informationen zum Konfigurieren der Generierung der XML-Dokumentationsdatei finden Sie unter -doc compiler-Option und GenerateDocumentationFile MSBuild-Eigenschaft.

Die XML-Datei kann als XML genutzt oder anderweitig bearbeitet werden. Diese Datei befindet sich im selben Verzeichnis wie die Ausgabe-EXE- oder DLL-Datei Ihres Projekts.

Die XML-Dokumentation beginnt mit '''. Die Verarbeitung dieser Kommentare weist einige Einschränkungen auf:

  • Die Dokumentation muss wohlgeformtes XML sein. Wenn das XML nicht wohlgeformt ist, wird eine Warnung generiert, und die Dokumentationsdatei enthält einen Kommentar, der besagt, dass ein Fehler aufgetreten ist.

  • Entwickler können ihren eigenen Satz von Tags erstellen. Es gibt einen empfohlenen Satz von Tags (siehe XML-Kommentartags). Einige der empfohlenen Tags haben eine besondere Bedeutung:

    • Das <param>-Tag wird verwendet, um Parameter zu beschreiben. Wenn es verwendet wird, überprüft der Compiler, ob der Parameter vorhanden ist und dass alle Parameter in der Dokumentation beschrieben werden. Wenn 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. Wenn die Überprüfung fehlschlägt, gibt der Compiler eine Warnung aus. Der Compiler berücksichtigt alle Imports-Anweisungen, wenn er nach einem Typ sucht, der im cref-Attribut beschrieben wird.

    • Das <Zusammenfassung>-Tag wird von IntelliSense in Visual Studio verwendet, um zusätzliche Informationen über einen Typ oder Member anzuzeigen.

Ausführliche Informationen über das Erstellen einer XML-Datei mit Dokumentationskommentaren finden Sie in den folgenden Themen:

Siehe auch