Kommentare in der XML-Dokumentation

Nach oben zu Quelltext-Editor

Übersicht

XML-Dokumentationskommentare werden:

• Durch drei Schrägstriche (///) eingeleitet
• Mit XML-Tags strukturiert
• Wie normale Codeblöcke oder Abschnitte aus- und eingeblendet (siehe Code-Folding verwenden)
• Von Delphi unterstützt

XML-Dok-Kommentare werden in der Symbolbeschreibung (bei erfolgreicher Analyse) angezeigt und auch vom Compiler beim Erzeugen der XML-Dokumentation (als devnotes-XML-Element) einbezogen.

Die XML-Tags müssen ordnungsgemäß geschlossen werden, wie z.B. <para>...</para>. Wird ein schließendes Element nicht gefunden, ist die XML-Repräsentation ungültig, und die Symbolbeschreibung kann die XML-Kommentare nicht anzeigen.

Beispiel für eine Delphi-Funktion mit XML-Dokumentationskommentaren

/// <summary> Removes the specified item from the collection
/// </summary>
/// <param name="Item">The item to remove
/// </param>
/// <param name="Collection">The group containing the item
/// </param>
/// <remarks>
/// If parameter "Item" is null, an exception is raised.
/// <see cref="EArgumentNilException" />
/// </remarks>
/// <returns>True if the specified item is successfully removed;
/// otherwise False is returned.
/// </returns>
function RemoveItem(Item: Pointer; Collection: Pointer): Boolean;
begin
  // Non-XML DOC comment
  // ...
end;

Weitere Beispiele für XML-Dok-Kommentare finden Sie in den folgenden Quelltextdateien:

• DSServer.pas
• DSCommonServer.pas
• DSHTTP.pas

XML-Elemente

Folgende Elemente können in XML-Dok-Kommentaren verwendet werden:

<summary>

Eine Zusammenfassung der Zielfunktion oder -klasse

<para>

Ein Absatz

<c>

Text in einer Schrift mit fester Breite

<code>

Vorformatierter Text, wie z.B. Quellcode

<remarks>

Anmerkungen zur Zielfunktion oder -klasse

<param name="ParameterName">

Der Name und die Beschreibung eines bestimmten Parameters

<see>

Referenz auf einen bestimmten Typ, ein Symbol oder einen Bezeichner

<returns>

Beschreibung des Rückgabewertes der Zielfunktion. Die Funktion könnte beispielsweise einen Fehlercode zurückgeben.

<exception cref="EExceptionTypeName">

Exception, die von einer Methode ausgelöst werden kann

<permission cref="PermissionType">

Berechtigungen einer Methode

Siehe auch

• XML-Dokumentationskommentare (C#-Programmierhandbuch)
• XML-Dokumentation für C++-Code (Vom Compiler generierte XML-Dokumentation)
• Code-Folding verwenden