Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Last revisionBoth sides next revision
de:entwickler:sourcecode-dokumentation [2012/07/15 14:11] fassede:entwickler:sourcecode-dokumentation [2012/07/17 21:41] – Fehlende Doxygen-Tags dokumentiert fasse
Line 1: Line 1:
 ====== Sourcecode-Dokumenation ====== ====== Sourcecode-Dokumenation ======
 ==== Doxygen ==== ==== 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. 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]].+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. Der Vorteil 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 ==== ==== HTML-Ansicht selber generieren ====
Line 17: Line 17:
  
 ==== Parameter dokumentieren ==== ==== 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.+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 ;)
  • de/entwickler/sourcecode-dokumentation.txt
  • Last modified: 2012/07/17 22:07
  • by fasse