XML Documentation mit Delphi – Hintergrund, Tags und Tipps


Seit Delphi 2005 (ich weiß nicht genau ab welcher Delphi Version, mindestens aber seit 2005) gibt es die Möglichkeit beim Compilieren eines Projekt automatisch eine XML Dokumentation dazu erstellen zu lassen. Dies generiert zu jeder Unit eine XML-Datei mit der „Dokumentation“ von allem, was in deren Implementation-Teil definiert wurde. Allerdings enthält diese Doku bis hierhin nur eine Auflistung der enthaltenen Funktionen, Typen, Klassen, etc. – ohne jegliche Beschreibung.

Das schöne an der eingebauten XML-Doku ist nun, dass die „richtige“ Dokumentation auch direkt im Quelltext erfolgen kann, über speziell formatierte Kommentare, die dem zu beschreibenden Element einfach vorangestellt werden.

/// <summary>Klassenbeschreibung</summary>
TMyClass = class
  {! <summary>Beschreibung der Prozedur MyMethod</summary>
     <parameter name="Param1">Erster Parameter</parameter>
     <example>Beispiel für die Anwendung</example>
     <todo>MyMethod implementieren...</todo>}
  procedure MyMethod( Param1 : Integer );
end;

Drei Slashes (oder {!}) markieren einen Dokumentations-Kommentar. Alle Kommentare (im Implementation-Teil), die so „markiert“ sind, werden in die XML-Datei übernommen, als Beschreibung des direkt nachfolgenden Elements (also der Klasse, Methode, Variable, etc.).

Wirklich interessant wird das ganze aber erst durch die Verwendung bestimmter Tags in den Kommentaren, denn die Informationen aus der XML-Doku werden auch für die HelpInsight-Tooltips von Delphi verwendet. Zum Beispiel wird Text, der mit dem Tag summary markiert wird, als Beschreibung der Funktion im Tooltip angezeigt, und über parameter können Beschreibungen der einzelnen Parameter angegeben werden. Prinzipiell können zwar beliebige Tags benutzt werden, es empfiehlt sich aber, die vom Microsoft für C# empfohlenen Tags zu benutzen. Der Großteil hiervon wird auch von Delphi verwendet.

Das größte Problem mit der XML Dokumentation ist allerdings, dass eben nur die XML-Dateien erzeugt werden, und die sind recht kryptisch und ohne weiteres nicht vernünftig lesbar. Will man die Dokumentation nicht nur für HelpInsight haben, dann müssen die erzeugten XML-Dateien irgendwie zur Anzeige aufbereitet werden. Ein entsprechendes Tool wird leider nicht mitgeliefert (es geht auch mit nachträglich heruntergeladenen „Bordmitteln“ – für meinen Geschmack aber zu umständlich). Und es existieren zwar Tools, die aus den XML-Dateien eine lesbare HTML-Doku oder auch Hilfedateien erzeugen können (z.B. Doc-o-Matic), aber die kosten Geld und nach jeder Änderung muss die Hilfe neu erstellt werden.

Nachdem ich nirgendwo im Internet eine Lösung für dieses Problem gefunden habe, die mir gefällt, habe ich angefangen meine eigene Lösung zu bauen, die aus HTML, XML, XSL und Javascript besteht und die Doku On-The-Fly anzeigen kann. Das Ganze funktioniert schon recht gut und ich werde es demnächst hier hochladen.

Vorher aber noch ein paar nette Tipps zur Verwendung der XML-Doku.

XMLDoc regions

Wer sich wirklich Mühe gibt und seinen Quelltext vernünftig dokumentiert wird schnell das Problem haben, dass vor lauter Dokumentation die eigentlichen Deklarationen untergehen. Eine Lösung hierfür ist (spätestens ab Delphi 2006) die Verwendung von Regions, die dann je nach Bedarf ein- und ausgeklappt werden können.

{$region 'xmldoc'}
 /// <summary>Beschreibung der Prozedur MyMethod</summary>
 /// <parameter name="Param1">Erster Parameter</parameter>
 /// <example>Beispiel für die Anwendung</example>
 /// <todo>MyMethod implementieren...</todo>
 {$endregion}
 procedure MyMethod( Param1 : Integer );

Das Ein- bzw. Ausblenden aller Doku-Regions einer Unit kann per IDE-Plugin auf einen Hotkey gelegt werden: In diesem Blog-Post wird beschrieben wie, und im Embarcadero Developer Network gibt es den Sourcecode auch direkt zum Download.

Live-Template für Region und Summary-Tag

Wer sich das Eingeben der XML-Dokumentation erleichtern will, der kann hierfür einfach folgendes Live-Template verwenden (es basiert auf dem xdoc-Template von Pawl Glowacki, das ich lediglich um die xmldoc-Region ergänzt habe).

<?xml version="1.0" encoding="utf-8">
<codetemplate xmlns="http://schemas.borland.com/Delphi/2005/codetemplates" version="1.0.0">
  <template name="xdoc" invoke="auto">
    <description>Help Insight XML Documentation comment with "summary" element</description>
    <author>CodeGea</author>

    <point name="comment">
      <text>documentation comment</text>
      <hint>XML Documentation comment goes here</hint>
    </point>

    <code language="Delphi" delimiter="|">
      <![CDATA[{$region 'xmldoc'}
        ///<summary>|comment|</summary>
	{$endregion}]]>
    </code>
  </template>
</codetemplate>

Bei aktivierter Template-Vervollständigung genügt es jetzt im Quelltext xdoc einzugeben und dann Tab zu drücken und schon wird die Region und ein summary-Tag als Start angelegt.

Eine erste Version des meines „XMLDoc Viewers“ ist jetzt online.


Kommentare sind geschlossen.