====== Sourcecode-Documentation ======
==== Doxygen ====
The documentation of our classes and functions should be done with[[http://www.doxygen.org|Doxygen]]. This program creates a [[https://www.admidio.org/dokusource|structured HTML documentation]] within the comment section of the source code using keywords. The documentation can also be downloaded offline access also [[https://sourceforge.net/projects/admidio/files/Dokusource/|downloaded]] for offline work. The advantage of the documentation with Doxygen is a good clear documentation in the source code itself, plus a well-formatted HTML representation without requiring a large amount of additional work. This page will now describe the most important keywords and formatting of Doxygen, which we need for Admidio. On the Doxygen page itself you will also find a guide to [[http://www.stack.nl/~dimitri/doxygen/docblocks.html|Adjust documentation]] and a [[http://www.stack.nl/~dimitri/doxygen/commands.html | Overview of all keywords]].

==== Generate HTML view  ====
If you've added formatted documentation and want to see the result in the HTML view, you have to create it with Doxygen. For this you download the [[http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc|current Version]] of Doxygen and install the program. Now you should have our configuration file of Doxygen downloaded. You can find the file **Admidio_Config_File** in SVN at:
  https://admidio.svn.sourceforge.net/svnroot/admidio/trunk/documentation/doxygen
Start Doxygen and choose among **File> Open** this file. "Our" Settings for Doxygen will now be set. You have only to check and adjust the two paths on the tab **Wizard** and the heading **Project** to your system and can create with **Run** the Doxygen documentation.

==== Format Comments for Doxygen ====
Comments must be specially marked so that they are recognized and processed by Doxygen as relevant. This is useful, but really only in class, method and function descriptions. This requires the comment normally is to be supplemented front of the class, method or function with special characters.
<code php>
// Description for subsequent function, as it was previously available in the source code.
function foo($param)
</code>
From this line of code should be the following syntax:
<code php>
/// Description for subsequent function, as it is optimized for Doxygen
function foo($param)
</code>
Once there, however, more than one line, following Doxygen comment optimized code should be used:
<code php>
/**
 * Description for subsequent function, as it is optimized for Doxygen
 * And more than one line
 */
function foo($param)
</code>
In a one-line comment a 3. Slash is appended, multiline comment at the beginning a 2nd asterisk.Now the comment will be considered in Doxygen.

==== Documenting Parameters ====
Parameters of functions or methods can be documented through a simple tag. For this purpose, the method only the tag **@ param** must be deposited in the comment section, followed by the parameter name and the description.
<code php>
///param $ user_id The user ID of the current user
</code>
Nestled in a method or function description that looks like
<code php>
/**
 * Description for subsequent function, as it is optimized for Doxygen
 * @param $user_id The user id of the current user
 */
</code>

==== Documenting Function return ====
Also, the return value of a function or method can be specially marked and appear as highlighted in the documentation. For this purpose, the method must have deposited only the tag **@ return** in the comment section, followed by the description of the return value.
<code php>
///return Returns the value of the element or the error message if a test failed
</code>
Nestled in a method or function description looks like this from
<code php>
/**
 * Description for subsequent function, as it is optimized for Doxygen
 * @return Returns the value of the element or the error message if a test failed
 */
</code>

==== Documenting Example Code ====
With Doxygen also sample code can be specifically shown, so that it is highlighted in the document and shows the syntax of the programming in color. This should first be defined with a kind of headline **@par** and then with **@ code** and **@encode ** the actual sample code embedded.
<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>

==== A complete documented function ====
In the example below you can see how the combination of all these syntax elements may look and comes out a beautiful clear Function documentation here:
<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 creates then [[https://www.admidio.org/dokusource/|this nice formatted HTML page]]. Now there are detailed documentation even in the code, and additionally as a HTML view with search. More can not be expected as a developer ;)