Sourcecode-Dokumenation [Admidio-Wiki]

Diese Seite ist nicht editierbar. Sie können den Quelltext sehen, jedoch nicht verändern. Kontaktieren Sie den Administrator, wenn Sie glauben, dass hier ein Fehler vorliegt.
====== Sourcecode-Dokumenation ======
==== Doxygen ====
Die Dokumentation unserer Klassen und Funktionen soll mit Hilfe von [[http://www.doxygen.org|Doxygen]] erfolgen. Dieses Programm kann mit Hilfe von Schlüsselwörtern innerhalb des Kommentarbereichs des Sourcecodes eine [[http://www.admidio.org/dokusource|übersichtliche HTML-Dokumentation]] erstellen. Die Dokumenation kann zum Offline-Zugriff auch [[https://sourceforge.net/projects/admidio/files/Dokusource/|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 [[http://www.stack.nl/~dimitri/doxygen/docblocks.html|Anpassung der Dokumentation]], sowie eine [[http://www.stack.nl/~dimitri/doxygen/commands.html|Übersicht über alle Schlüsselwörter]].

==== HTML-Ansicht selber generieren ====
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 [[http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc|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 für Doxygen formatieren ====
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. <code php>// Beschreibung zur nachfolgenden Funktion, wie sie bisher im Sourcecode vorhanden war
function foo($param)</code> Aus dieser Codezeile sollte dann folgende Syntax werden: <code php>/// Beschreibung zur nachfolgenden Funktion, wie sie für Doxygen optimiert ist
function foo($param)</code> Sobald es allerdings über mehrere Zeilen geht, sollte folgender Doxygen optimierter Kommentarcode genutzt werden: <code php>/** Beschreibung zur nachfolgenden Funktion, wie sie für Doxygen optimiert ist
 * und über mehrere Zeilen geht
 */
function foo($param)</code>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 dokumentieren ====
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.<code php>/// @param $user_id The user id of the current user</code> Eingebettet in eine Methoden- oder Funktionsbeschreibung sieht das dann so aus <code php>/** Beschreibung zur nachfolgenden Funktion, wie sie für Doxygen optimiert ist
 *  @param $user_id The user id of the current user
 */</code>

==== Funktionsrückgabe dokumentieren ====
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.<code php>/// @return Returns the value of the element or the error message if a test failed</code> Eingebettet in eine Methoden- oder Funktionsbeschreibung sieht das dann so aus <code php>/** 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
 */</code>

==== Beispielcode dokumentieren ====
Ü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. <code php>/**  @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 
 */</code>

==== Ein komplette dokumentierte Funktion ====
Im nachfolgenden Beispiel seht ihr wie die Kombination all dieser Syntaxelemente aussehen kann und eine schöne übersichtliche Funktionsdokumentation dabei herauskommt: <code php>/// 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)
{
  ...
}</code>Doxygen erstellt daraus dann [[http://admidio.org/dokusource/d1/da0/function_8php.html#ac37c2a5fcd7dc5b31885f0de8a589891|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 ;)