Differences

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

--- en:entwickler:sourcecode-dokumentation [2015/11/30 10:04] – [Documenting Example Code] ximex
+++ en:entwickler:sourcecode-dokumentation [2016/12/03 14:53] (current) – ximex
@@ Line 1: / Line 1: @@
 ====== Sourcecode-Documentation ======
 ==== Doxygen ====
-The documentation of our classes and functions should be done with[[http://www.doxygen.org | Doxygen]]. This program creates a[[http://www.admidio.org/dokusource|structured HTML documentation]] within the comment section of the source code using keywords. The documenation 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]].
+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  ====
@@ Line 9: / Line 9: @@
 ==== 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.
+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.
-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
+<code php>
-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
+// Description for subsequent function, as it was previously available in the source code.
-* And more than one line
+function foo($param)
-* /
+</code>
-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.
+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
+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
+<code php>
- */</code>
+///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
+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
+<code php>
- */</code>
+///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 embeded.
+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>
 / **
@@ Line 39: / Line 68: @@
 ==== 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
+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:
-/** 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.
+<code php>
- *  But the function can also be used with every array and their elements. You can set several flags (like required value, datatype …)
+/// Verify the content of an array element if it's the expected datatype
- *  that should be checked.
+/**
- *  @param $array The array with the element that should be checked
+ * 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.
- *  @param $variableName Name of the array element that should be checked
+ * But the function can also be used with every array and their elements. You can set several flags (like required value, datatype …)
- *  @param $datatype The datatype like @b string, @b numeric, @b boolean or @b file that is expected and which will be checked
+ * that should be checked.
- *  @param $defaultValue A value that will be set if the variable has no value
+ * @param $array The array with the element that should be checked
- *  @param $requireValue If set to @b true than a value is required otherwise the function returns an error
+ * @param $variableName Name of the array element that should be checked
- *  @param $validValues An array with all values that the variable could have. If another value is found than the function returns an error
+ * @param $datatype The datatype like @b string, @b numeric, @b boolean or @b file that is expected and which will be checked
- *  @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
+ * @param $defaultValue A value that will be set if the variable has no value
- *  @return Returns the value of the element or the error message if a test failed
+ * @param $requireValue If set to @b true than a value is required otherwise the function returns an error
- *  @par Examples
+ * @param $validValues An array with all values that the variable could have. If another value is found than the function returns an error
- *  @code   // numeric value that would get a default value 0 if not set
+ * @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
- *  $getDateId = admFuncVariableIsValid($_GET, 'dat_id', 'numeric', 0);
+ * @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
+ * // string that will be initialized with text of id DAT_DATES
- *  $getHeadline = admFuncVariableIsValid($_GET, 'headline', 'string', $g_l10n->get('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
+ * // string initialized with actual and the only allowed values are actual and old
- *  $getMode = admFuncVariableIsValid($_GET, 'mode', 'string', 'actual', false, array('actual', 'old')); @endcode
+ * $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 [[http://admidio.org/dokusource/d1/da0/function_8php.html#ac37c2a5fcd7dc5b31885f0de8a589891|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 ;)
+}
+</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 ;)