Sourcecode-Dokumenation

Die Dokumentation unserer Klassen und Funktionen soll mit Hilfe von Doxygen erfolgen. Dieses Programm kann mit Hilfe von Schlüsselwörtern innerhalb des Kommentarbereichs des Sourcecodes eine übersichtliche HTML-Dokumentation erstellen. Diese Seite soll nun die wichtigsten Schlüsselwörter und Formatierungen von Doxygen beschreiben, die wir für Admidio benötigen. Auf der Doxygen-Seite selber findest du auch eine Anleitung zur Anpassung der Dokumentation, sowie eine Übersicht über alle Schlüsselwörter.

Falls du selber formatierte Dokumentation hinzugefügt hast und das Ergebnis in der HTML-Ansicht sehen willst, musst du diese mit Doxygen erstellen. Dazu lädst du die aktuelle Version von Doxygen herunter und installierst das Programm. Nun solltest du noch unsere Konfigurationsdatei von Doxygen herunterladen. Du findest die Datei Admidio_Config_File im SVN unter:

https://admidio.svn.sourceforge.net/svnroot/admidio/trunk/documentation/doxygen

Starte Doxygen und wähle unter File > Open diese Datei aus. Es werden nun “unsere” Einstllungen für Doxygen gesetzt. Du musst nur noch die beiden Pfade auf dem Karteireiter Wizard und der Rubrik Project prüfen und an dein System anpassen und kannst dann unter Run die Doxygen-Dokumentation erstellen.

Kommentare müssen speziell markiert werden, damit sie von Doxygen als relevant erkannt und verarbeitet werden. Sinnvoll ist dies aber eigentlich nur bei Klassen-, Methoden- und Funktionsbeschreibungen. Dazu muss der Kommentar, der i.d.R. vor der Klasse, Methode oder Funktion steht nur durch spezielle Zeichen ergänzt werden.

// Beschreibung zur nachfolgenden Funktion, wie sie bisher im Sourcecode vorhanden war
function foo($param)

Aus dieser Codezeile sollte dann folgende Syntax werden:

/** Beschreibung zur nachfolgenden Funktion, wie sie für Doxygen optimiert ist
*/
function foo($param)

Es sollte die Syntax für mehrzeiligen Kommentar genutzt werden /* Kommentar */, damit der Kommentar später einfach erweitert werden kann und diese Syntax wird dann einfach um ein zusätzliches * erweitert /** Kommentar */.

Möchte man dennoch einen einzeligen Kommentar für Doxygen formatieren, so kann man einfach einen 3. Slash anhängen:

/// ein einzeiliger Kommentar