DoxyGen

Dokumentation ist für Quellcode ebenso wichtig, wie das Erarbeiten und Testen von Programmlogiken.

Und so stellt sich natürlich auch für das GATE Projekt die Frage, wie mit dem Thema umgegangen werden soll.

Machen wir’s kurz: Die Doxygen-Regeln für Kommentare werden als Richtlinie dienen.

In den vergangenen Monaten hat das GATE Projekt nun doch schon einige hunderte Funktionen erhalten und neben einer ordentlichen Beschreibung aller Parameter wird eine strukturierte Auflistung des gesamten Frameworks notwendig.

Doxygen bieten den Vorteil, dass über eine GUI die Einstellungen für eine Indizierung alle Quelldateien vorgenommen werden kann, die dann von Konsolenprogrammen (und somit automatisiert) abgearbeitet werden.

Die Ausgabe als HTML-Seiten ist ebenso nützlich, denn auf diese Weise steht einer Publikation im Web nichts mehr im Wege.

Am wichtigsten ist aber das rasche Einlernen der Kommentar-Strukturen. Denn wenn erst eine Million Zeilen geschrieben ist, wird es verdammt mühsam, wenn man jede Kommentarzeile anpassen muss, um sie in Doxygen richtig darzustellen.

Das Programm nutzt also ein bestimmtes Format in Programmkommentaren um daraus eine ansprechende Dokumentation zu generieren.

Im GATE Projekt werden nicht alle Funktionen automatisch in der Dokumentation aufscheinen, sondern nur die Interface-Relevanten. Daher muss jede zu dokumentierende Datei am Beginn den Eintrag

/** @file
 *  @brief Description of this file
 */

enthalten.

Mit einem einleitenden Stern (*) und Kleinerzeichen (<) können typedef oder struct-Member um eine Beschreibung erweitert werden.

struct X
{
  int a;  /**< First member */
  int b;  /**< Second member */
};

Und Funktionen wie auch ganze struct Deklarationen werden mit einem voran gestellten Kommentarblock wie folgt näher beschrieben:

/**
 * @brief Does something with 2 arguments
 * @param dummy A dummy variable with any valid value
 * @param foobar The counterpart of the dummy with any valid value
 * @return value returns a GATE_RESULT_* code
 */
gate_resul_t gate_do_something(int dummy, int foobar);

Und so geht es weiter …

Ich hoffe die nötige Zeit zu finden, die schon bestehenden Funktionen noch nachzudokumentieren … denn es ist ja durchaus bekannt, dass Programmierer nicht gerne Dokumentationen schreiben.
Wie auch immer, nachdem dieses Projekt mein bisheriges Wissen konservieren soll, ist es eben auch notwendig in diesen Apfel zu beißen.