Sourcecode-Documentation

The documentation of our classes and functions should be done withDoxygen. This program creates a structured HTML documentation within the comment section of the source code using keywords. The documentation can also be downloaded offline access also 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 Adjust documentation and a Overview of all keywords.

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 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.

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.

// Description for subsequent function, as it was previously available in the source code.
function foo($param)

From this line of code should be the following syntax:

/// Description for subsequent function, as it is optimized for Doxygen
function foo($param)

Once there, however, more than one line, following Doxygen comment optimized code should be used:

/**
 * Description for subsequent function, as it is optimized for Doxygen
 * And more than one line
 */
function foo($param)

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.

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.

///param $ user_id The user ID of the current user

Nestled in a method or function description that looks like

/**
 * Description for subsequent function, as it is optimized for Doxygen
 * @param $user_id The user id of the current user
 */

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.

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

Nestled in a method or function description looks like this from

/**
 * 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
 */

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.

/ **
 * @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 
 */

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:

/// 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 creates then 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 ;)