Gegen Internetzensur
Stoppt die Vorratsdatenspeicherung! Jetzt klicken & handeln!Willst du auch bei der Aktion teilnehmen? Hier findest du alle relevanten Infos und Materialien:
  • Flickr Photos

    www.flickr.com
16. Nov
Fre

Mein SVN und ich, die Zweite: Doxygen

Man bereitet also mal wieder alles vor für Doxygen, aber dieses Mal will man klüger sein: Wenn Subversion es (wie CVS) erlaubt, bestimmte Schlüsselwörter zu verfolgen und damit die Dateiinformationen in den Sourceheadern immer auf dem letzten Stand der Dinge zu halten – wer war’s und wann war’s – ohne, dass man selbst daran denken muss, warum dann diese Information nicht gleich formschön in Doxygen verwerten?

Das Ganze sieht im Quellcode in etwa so aus:

  1. /*!
  2.  * \date $Date: 2007-11-15 16:33:30 +0100 (Do, 15 Nov 2007) $
  3.  * \version $Rev: 5 $
  4.  * \author $Author: lutz $
  5.  */

oder

  1. /**
  2.  * @date $Date: 2007-11-15 16:33:30 +0100 (Do, 15 Nov 2007) $
  3.  * @version $Rev: 5 $
  4.  * @author $Author: lutz $
  5.  */

Alles recht simpel, lediglich Doxygen verschluckt sich daran. Wer es einmal probiert hat weiß, dass spätestens nach dem Doppelpunkt in der Dokumentation Schluss mit lustig ist.

Eine Lösung schaffen die Variablen FILE_VERSION_FILTER, INPUT_FILTER und FILTER_SOURCE_FILES in der Doxygen-Direktivendatei (Doxyfile). Erstere gibt eine ausführbare Datei an, welche immer dann aufgerufen wird, wenn es darum geht, zu einer zu dokumentierenden Datei die Version ausfindig zu machen. Ähnlich verhält es sich mit Variable zwei, nur dass dieser Filter immer benutzt wird. (Gesetzt den Fall, FILTER_SOURCE_FILES = YES).

Für diesen Zweck kann ich uneingeschränkt das Kommandozeilentool sed empfehlen. Da der Stream Editor allerdings unter Windows nicht von Hause aus zu haben ist, muss man ihn sich als Windowsuser ohne Cygwin anderswo ausleihen: UnixKit, UnxUtils und GnuWin32 sind gute Anlaufstellen.

Sed ermöglicht es im “substitute”-Modus, seine Eingabe nach bestimmten Kriterien (namentlich Regular Expressions) zu filtern und zu ändern, bevor es sie zurückgibt.
Kurzes Intro: sed "s/Such-Regex/Ziel-Regex/" Datei oder sed -e "s/Such-Regex 1/Ziel-Regex 1/" -e "s/Such-Regex 2/Ziel-Regex 2/" [...] Datei.

Zwei Beispiele in Form einer Windows-Batchdatei:

Windows Batch [Show Plain Code]:
  1. @echo off
  2. REM Methode eins:
  3. REM \tag        $keyword: string $ –> \tag string
  4. REM @tag        $keyword: string $ — > @tag string
  5. sed "s/\([\\@]\w*[      ]*[^\$]*[       ]*\)\$\w*:\ *\([^\$]*\)\ *\$/\1\2/" %1
  6.  
  7. REM Methode 2:
  8. REM $keyword: string $ –> string
  9. sed "s/\$\w*:\ *\([^\$]*\)\ *\$/\1/" %1

Natürlich sollte eine reelle Batchdatei nur einen der beiden Befehle enthalten. Die Ausdrücke lesen sich wie folgt:

  • Methode eins durchsucht die zu filternde Quelldatei nach Doxygen-Tags, auf die ein SVN-Schlüsselwort folgt.
    Doxygen-Tags können mit Backslash oder @-Zeichen beginnen ([\\@]), bestehen aus mehreren “Wort”-Zeichen (\w*), gefolgt von Leerzeichen oder Tabs ([ ]* – Hinweis: Tabs ausschreiben; d.h. TAB drücken!). Danach folgen mehrere, beliebige Zeichen, außer $, und wieder Leerzeichen oder Tabs ([^\$]*[ ]*). Es folgt: Ein $, ein Wort, ein Doppelpunkt, Leerzeichen, alles außer $, Leerzeichen, sowie das abschließende Dollarzeichen (\$\w*:\ *\([^\$]*\)\ *\$). Sowohl das Doxygen-Tag, als auch der Inhalt des Subversion-Keywords werden mit Regex-Gruppen umschlossen (Hinweis: Die runden Klammern müssen escaped werden, damit Sed sie als solche annimmt) und später durch die Rückreferenzen \1 und \2 wieder zusammengefügt.

    Vorteil: Nur dort, wo Doxygen die Keyword abfragt, werden sie auch ersetzt. Nachteil: Subversion-Schlüsselwörter, die sich nicht in einer Zeile hinter einem Doxygen-Schlüsselwort befinden, werden nicht gefiltert. Das ist zwar gewünscht, wird aber dann problematisch, wenn das letzte Schlüsselwort – ein paar Zeilen höher und damit außer Reichweite – etwa \par, \remarks o.ä. geheißen hat. Das Keyword würde von Doxygen ungefiltert zu diesem Abschnitt hinzugefügt werden und man hat den selben Salat wie zuvor.

  • Methode zwei ist die Hau-Drauf-Methode: Sämtliche SVN-Keywords werden gefiltert.
    Der Weg ist derselbe Wie oben beschrieben, nur dass es dieses Mal nur eine einzelne Rückreferenz gibt und die RegEx etwas kürzer ist.

    Vorteil: Keine verhunzten Keywords mehr in der Dokumentation. Nachteil: Auch dort, wo Doxygen sonst nicht greift, werden die Keywords gefiltert. Bei aktiviertem INLINE_SOURCES oder SOURCE_BROWSER kann das zu verbogenen Kommentaren führen. (Allerdings ausschließlich in der Dokumentation und auch nur, wenn man sich darauf verlässt, dass die Keywords so schrullig aussehen, wie man es von SVN gewohnt ist. Wer ohnehin sowas wie Id: $Id$ schreibt, hat vermutlich nichts verloren.)

Wer ganz hart ist, braucht sich dafür nicht einmal ein Shellscript oder eine Batchdatei anzulegen: So lang ist der Befehl ja nicht.

Wieder ein Problem weniger.

3 Antworten zu „Mein SVN und ich, die Zweite: Doxygen”

  1. #1~Surfer

    In Sachen Doxygen führt nichts an diesem Artikel vorbei:
    http://www.netzwerk-des-wissens.de/ArtikelZusammenstellen_DB.php?artikel_id=29

  2. #2~Surfer

    In Sachen Doxygen führt nichts an diesem Artikel vorbei:
    Link zum Artikel

  3. #3~Mac

    … oder am Handbuch.