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)

Sobald es allerdings über mehrere Zeilen geht, sollte folgender Doxygen optimierter Kommentarcode genutzt werden:

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

Beim einzeiligen Kommentar wird ein 3. Slash angehangen, beim mehrzeiligen Kommentar wird am Anfang ein 2. Sternchen angehangen und schon wird der Kommentar von Doxygen berücksichtigt.

Parameter von Funktionen oder Methoden können über einen einfachen Tag dokumentiert werden. Dazu muss im Kommentarbereich der Methode nur das Tag @param hinterlegt werden, gefolgt von dem Namen des Parameters und der Beschreibung.