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. Die Dokumenation kann zum Offline-Zugriff auch heruntergeladen werden. Der Vorteil der Dokumentation mit Doxygen ist eine gute übersichtliche Dokumentation im Sourcecode selber und zusätzlich eine gut formatierte HTML Darstellung ohne dass ein großer Mehraufwand entsteht. 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.

/// @param $user_id The user id of the current user

Eingebettet in eine Methoden- oder Funktionsbeschreibung sieht das dann so aus

/** Beschreibung zur nachfolgenden Funktion, wie sie für Doxygen optimiert ist
 *  @param $user_id The user id of the current user
 */

Auch der Rückgabewert einer Funktion oder Methode kann speziell gekennzeichnet werden und erscheint so hervorgehoben in der Dokumentation. Dazu muss im Kommentarbereich der Methode nur das Tag @return hinterlegt werden, gefolgt von der Beschreibung des Rückgabewerts.

/// @return Returns the value of the element or the error message if a test failed

Eingebettet in eine Methoden- oder Funktionsbeschreibung sieht das dann so aus

/** Beschreibung zur nachfolgenden Funktion, wie sie für Doxygen optimiert ist
 *  @return Returns the value of the element or the error message if a test failed
 */

Über Doxygen kann auch Beispielcode speziell dargestellt werden, so dass dieser in der Dokumentation hervorgehoben und die Syntax der Programmiersprache farblich dargestellt wird. Dazu sollte zuerst eine Art Überschrift mit @par definiert werden und danach mit @code und @endcode der eigentliche Beispielcode umgeben werden.

/**  @par Examples
 *  @code   $getDateId = admFuncVariableIsValid($_GET, 'dat_id', 'numeric', 0);
 *
 *  // string that will be initialized with text of id DAT_DATES
 *  $getHeadline = admFuncVariableIsValid($_GET, 'headline', 'string', $g_l10n->get('DAT_DATES')); @endcode 
 */

Im nachfolgenden Beispiel seht ihr wie die Kombination all dieser Syntaxelemente aussehen kann und eine schöne übersichtliche Funktionsdokumentation dabei herauskommt:

/// Verify the content of an array element if it's the expected datatype
/** The function is designed to check the content of @b $_GET and @b $_POST elements and should be used at the beginning of a script.
 *  But the function can also be used with every array and their elements. You can set several flags (like required value, datatype …) 
 *  that should be checked.
 *  @param $array The array with the element that should be checked
 *  @param $variableName Name of the array element that should be checked
 *  @param $datatype The datatype like @b string, @b numeric, @b boolean or @b file that is expected and which will be checked
 *  @param $defaultValue A value that will be set if the variable has no value
 *  @param $requireValue If set to @b true than a value is required otherwise the function returns an error
 *  @param $validValues An array with all values that the variable could have. If another value is found than the function returns an error
 *  @param $directOutput If set to @b true the function returns only the error string, if set to false a html message with the error will be returned
 *  @return Returns the value of the element or the error message if a test failed 
 *  @par Examples
 *  @code   // numeric value that would get a default value 0 if not set
 *  $getDateId = admFuncVariableIsValid($_GET, 'dat_id', 'numeric', 0);
 *
 *  // string that will be initialized with text of id DAT_DATES
 *  $getHeadline = admFuncVariableIsValid($_GET, 'headline', 'string', $g_l10n->get('DAT_DATES'));
 *
 *  // string initialized with actual and the only allowed values are actual and old
 *  $getMode = admFuncVariableIsValid($_GET, 'mode', 'string', 'actual', false, array('actual', 'old')); @endcode
 */
function admFuncVariableIsValid($array, $variableName, $datatype, $defaultValue = null, $requireValue = false, $validValues = null, $directOutput = false)
{
  ...
}

Doxygen erstellt daraus dann diese schöne formatierte HTML-Seite. Nun gibt es die ausführliche Dokumentation einmal im Code und zusätzlich noch als HTML-Ansicht mit Suchfunktion. Mehr kann man als Entwickler nicht erwarten ;)