Many PHPDocs, some unused and dyn declared vars

many PHPDocs
some unused variables
some dynamically declared variables declared

1 files changed, 95 insertions, 3 deletions

diff --git a/inc/form.php b/inc/form.php
index fadc71d3e..00eea9b3a 100644
--- a/inc/form.php
+++ b/inc/form.php
@@ -52,6 +52,7 @@ class Doku_Form {
      * @param bool|string $action  (optional, deprecated) submit URL, defaults to current page
      * @param bool|string $method  (optional, deprecated) 'POST' or 'GET', default is POST
      * @param bool|string $enctype (optional, deprecated) Encoding type of the data
+     *
      * @author  Tom N Harris <tnharris@whoopdedo.org>
      */
     function Doku_Form($params, $action=false, $method=false, $enctype=false) {
@@ -84,6 +85,7 @@ class Doku_Form {
      * Usually results in a border drawn around the form.
      *
      * @param   string  $legend Label that will be printed with the border.
+     *
      * @author  Tom N Harris <tnharris@whoopdedo.org>
      */
     function startFieldset($legend) {
@@ -115,6 +117,7 @@ class Doku_Form {
      *
      * @param   string  $name   Field name.
      * @param   string  $value  Field value. If null, remove a previously added field.
+     *
      * @author  Tom N Harris <tnharris@whoopdedo.org>
      */
     function addHidden($name, $value) {
@@ -132,6 +135,7 @@ class Doku_Form {
      * If string, it is printed without escaping special chars.   *
      *
      * @param   string|array  $elem   Pseudo-tag or string to add to the form.
+     *
      * @author  Tom N Harris <tnharris@whoopdedo.org>
      */
     function addElement($elem) {
@@ -145,6 +149,7 @@ class Doku_Form {
      *
      * @param   string       $pos  0-based index where the element will be inserted.
      * @param   string|array $elem Pseudo-tag or string to add to the form.
+     *
      * @author  Tom N Harris <tnharris@whoopdedo.org>
      */
     function insertElement($pos, $elem) {
@@ -158,6 +163,7 @@ class Doku_Form {
      *
      * @param   int          $pos  0-based index the element will be placed at.
      * @param   string|array $elem Pseudo-tag or string to add to the form.
+     *
      * @author  Tom N Harris <tnharris@whoopdedo.org>
      */
     function replaceElement($pos, $elem) {
@@ -172,7 +178,8 @@ class Doku_Form {
      * Gets the position of the first of a type of element.
      *
      * @param   string  $type   Element type to look for.
-     * @return  int     position of element if found, otherwise false
+     * @return  int|false     position of element if found, otherwise false
+     *
      * @author  Tom N Harris <tnharris@whoopdedo.org>
      */
     function findElementByType($type) {
@@ -189,7 +196,8 @@ class Doku_Form {
      * Gets the position of the element with an ID attribute.
      *
      * @param   string  $id     ID of the element to find.
-     * @return  int     position of element if found, otherwise false
+     * @return  int|false     position of element if found, otherwise false
+     *
      * @author  Tom N Harris <tnharris@whoopdedo.org>
      */
     function findElementById($id) {
@@ -207,7 +215,8 @@ class Doku_Form {
      *
      * @param   string  $name   Attribute name.
      * @param   string  $value  Attribute value.
-     * @return  int     position of element if found, otherwise false
+     * @return  int|false     position of element if found, otherwise false
+     *
      * @author  Tom N Harris <tnharris@whoopdedo.org>
      */
     function findElementByAttribute($name, $value) {
@@ -227,6 +236,7 @@ class Doku_Form {
      *
      * @param   int     $pos    0-based index
      * @return  array reference  pseudo-element
+     *
      * @author  Tom N Harris <tnharris@whoopdedo.org>
      */
     function &getElementAt($pos) {
@@ -243,6 +253,8 @@ class Doku_Form {
      * 'form_$type'. The function should return the HTML to be printed.
      *
      * @author  Tom N Harris <tnharris@whoopdedo.org>
+     *
+     * @return string html of the form
      */
     function getForm() {
         global $lang;
@@ -310,6 +322,7 @@ class Doku_Form {
  * @param   string  $tag    Tag name.
  * @param   array   $attrs  Optional attributes.
  * @return  array   pseudo-tag
+ *
  * @author  Tom N Harris <tnharris@whoopdedo.org>
  */
 function form_makeTag($tag, $attrs=array()) {
@@ -326,6 +339,7 @@ function form_makeTag($tag, $attrs=array()) {
  * @param   string  $tag    Tag name.
  * @param   array   $attrs  Optional attributes.
  * @return  array   pseudo-tag
+ *
  * @author  Tom N Harris <tnharris@whoopdedo.org>
  */
 function form_makeOpenTag($tag, $attrs=array()) {
@@ -341,6 +355,7 @@ function form_makeOpenTag($tag, $attrs=array()) {
  *
  * @param   string  $tag    Tag name.
  * @return  array   pseudo-tag
+ *
  * @author  Tom N Harris <tnharris@whoopdedo.org>
  */
 function form_makeCloseTag($tag) {
@@ -358,6 +373,7 @@ function form_makeCloseTag($tag) {
  * @param   string  $text   Text to fill the field with.
  * @param   array   $attrs  Optional attributes.
  * @return  array   pseudo-tag
+ *
  * @author  Tom N Harris <tnharris@whoopdedo.org>
  */
 function form_makeWikiText($text, $attrs=array()) {
@@ -378,6 +394,7 @@ function form_makeWikiText($text, $attrs=array()) {
  * @param   string  $value  (optional) Displayed label. Uses $act if not provided.
  * @param   array   $attrs  Optional attributes.
  * @return  array   pseudo-tag
+ *
  * @author  Tom N Harris <tnharris@whoopdedo.org>
  */
 function form_makeButton($type, $act, $value='', $attrs=array()) {
@@ -406,6 +423,7 @@ function form_makeButton($type, $act, $value='', $attrs=array()) {
  *                          reference it with a 'for' attribute.
  * @param   array   $attrs  Optional attributes.
  * @return  array   pseudo-tag
+ *
  * @author  Tom N Harris <tnharris@whoopdedo.org>
  */
 function form_makeField($type, $name, $value='', $label=null, $id='', $class='', $attrs=array()) {
@@ -522,6 +540,18 @@ function form_makeRadioField($name, $value='1', $label=null, $id='', $class='',
  * a string.
  *
  * @author  Tom N Harris <tnharris@whoopdedo.org>
+ *
+ * @param string           $name     Name attribute of the input.
+ * @param string[]|array[] $values   The list of values can be strings, arrays of (value,text),
+ *                                   or an associative array with the values as keys and labels as values.
+ * @param string|int       $selected default selected value, string or index number
+ * @param string           $class    Class attribute of the label. If this is 'block',
+ *                                   then a line break will be added after the field.
+ * @param string           $label    Label that will be printed before the input.
+ * @param string           $id       ID attribute of the input. If set, the label will
+ *                                   reference it with a 'for' attribute.
+ * @param array            $attrs    Optional attributes.
+ * @return array   pseudo-tag
  */
 function form_makeMenuField($name, $values, $selected='', $label=null, $id='', $class='', $attrs=array()) {
     if (is_null($label)) $label = $name;
@@ -556,6 +586,18 @@ function form_makeMenuField($name, $values, $selected='', $label=null, $id='', $
  * Items are selected by supplying its value or an array of values.
  *
  * @author  Tom N Harris <tnharris@whoopdedo.org>
+ *
+ * @param string           $name     Name attribute of the input.
+ * @param string[]|array[] $values   The list of values can be strings, arrays of (value,text),
+ *                                   or an associative array with the values as keys and labels as values.
+ * @param array|string     $selected value or array of values of the items that need to be selected
+ * @param string           $class    Class attribute of the label. If this is 'block',
+ *                                   then a line break will be added after the field.
+ * @param string           $label    Label that will be printed before the input.
+ * @param string           $id       ID attribute of the input. If set, the label will
+ *                                   reference it with a 'for' attribute.
+ * @param array            $attrs    Optional attributes.
+ * @return array   pseudo-tag
  */
 function form_makeListboxField($name, $values, $selected='', $label=null, $id='', $class='', $attrs=array()) {
     if (is_null($label)) $label = $name;
@@ -595,6 +637,9 @@ function form_makeListboxField($name, $values, $selected='', $label=null, $id=''
  * Attributes are passed to buildAttributes()
  *
  * @author  Tom N Harris <tnharris@whoopdedo.org>
+ *
+ * @param array $attrs attributes
+ * @return string html of tag
  */
 function form_tag($attrs) {
     return '<'.$attrs['_tag'].' '.buildAttributes($attrs,true).'/>';
@@ -608,6 +653,9 @@ function form_tag($attrs) {
  * Attributes are passed to buildAttributes()
  *
  * @author  Tom N Harris <tnharris@whoopdedo.org>
+ *
+ * @param array $attrs attributes
+ * @return string html of tag
  */
 function form_opentag($attrs) {
     return '<'.$attrs['_tag'].' '.buildAttributes($attrs,true).'>';
@@ -621,6 +669,9 @@ function form_opentag($attrs) {
  * There are no attributes.
  *
  * @author  Tom N Harris <tnharris@whoopdedo.org>
+ *
+ * @param array $attrs attributes
+ * @return string html of tag
  */
 function form_closetag($attrs) {
     return '</'.$attrs['_tag'].'>';
@@ -634,6 +685,9 @@ function form_closetag($attrs) {
  * Attributes are passed to buildAttributes()
  *
  * @author  Tom N Harris <tnharris@whoopdedo.org>
+ *
+ * @param array $attrs attributes
+ * @return string html
  */
 function form_openfieldset($attrs) {
     $s = '<fieldset '.buildAttributes($attrs,true).'>';
@@ -648,6 +702,8 @@ function form_openfieldset($attrs) {
  * There are no attributes.
  *
  * @author  Tom N Harris <tnharris@whoopdedo.org>
+ *
+ * @return string html
  */
 function form_closefieldset() {
     return '</fieldset>';
@@ -661,6 +717,9 @@ function form_closefieldset() {
  * Value is passed to formText()
  *
  * @author  Tom N Harris <tnharris@whoopdedo.org>
+ *
+ * @param array $attrs attributes
+ * @return string html
  */
 function form_hidden($attrs) {
     return '<input type="hidden" name="'.$attrs['name'].'" value="'.formText($attrs['value']).'" />';
@@ -674,6 +733,9 @@ function form_hidden($attrs) {
  * Text will be passed to formText(), attributes to buildAttributes()
  *
  * @author  Tom N Harris <tnharris@whoopdedo.org>
+ *
+ * @param array $attrs attributes
+ * @return string html
  */
 function form_wikitext($attrs) {
     // mandatory attributes
@@ -693,6 +755,9 @@ function form_wikitext($attrs) {
  * Other attributes are passed to buildAttributes()
  *
  * @author  Tom N Harris <tnharris@whoopdedo.org>
+ *
+ * @param array $attrs attributes
+ * @return string html
  */
 function form_button($attrs) {
     $p = (!empty($attrs['_action'])) ? 'name="do['.$attrs['_action'].']" ' : '';
@@ -708,6 +773,9 @@ function form_button($attrs) {
  * Other attributes are passed to buildAttributes() for the input tag.
  *
  * @author  Tom N Harris <tnharris@whoopdedo.org>
+ *
+ * @param array $attrs attributes
+ * @return string html
  */
 function form_field($attrs) {
     $s = '<label';
@@ -729,6 +797,9 @@ function form_field($attrs) {
  * Other attributes are passed to buildAttributes() for the input tag.
  *
  * @author  Tom N Harris <tnharris@whoopdedo.org>
+ *
+ * @param array $attrs attributes
+ * @return string html
  */
 function form_fieldright($attrs) {
     $s = '<label';
@@ -750,6 +821,9 @@ function form_fieldright($attrs) {
  * Other attributes are passed to buildAttributes() for the input tag.
  *
  * @author  Tom N Harris <tnharris@whoopdedo.org>
+ *
+ * @param array $attrs attributes
+ * @return string html
  */
 function form_textfield($attrs) {
     // mandatory attributes
@@ -773,6 +847,9 @@ function form_textfield($attrs) {
  * Other attributes are passed to buildAttributes() for the input tag.
  *
  * @author  Tom N Harris <tnharris@whoopdedo.org>
+ *
+ * @param array $attrs attributes
+ * @return string html
  */
 function form_passwordfield($attrs) {
     // mandatory attributes
@@ -798,6 +875,9 @@ function form_passwordfield($attrs) {
  * Other attributes are passed to buildAttributes() for the input tag
  *
  * @author  Michael Klier <chi@chimeric.de>
+ *
+ * @param array $attrs attributes
+ * @return string html
  */
 function form_filefield($attrs) {
     $s = '<label';
@@ -824,6 +904,9 @@ function form_filefield($attrs) {
  * $attrs['value'][1] is constructed as well.
  *
  * @author  Tom N Harris <tnharris@whoopdedo.org>
+ *
+ * @param array $attrs attributes
+ * @return string html
  */
 function form_checkboxfield($attrs) {
     // mandatory attributes
@@ -853,6 +936,9 @@ function form_checkboxfield($attrs) {
  * Other attributes are passed to buildAttributes() for the input tag.
  *
  * @author  Tom N Harris <tnharris@whoopdedo.org>
+ *
+ * @param array $attrs attributes
+ * @return string html
  */
 function form_radiofield($attrs) {
     // mandatory attributes
@@ -879,6 +965,9 @@ function form_radiofield($attrs) {
  * Other attributes are passed to buildAttributes() for the input tag.
  *
  * @author  Tom N Harris <tnharris@whoopdedo.org>
+ *
+ * @param array $attrs attributes
+ * @return string html
  */
 function form_menufield($attrs) {
     $attrs['size'] = '1';
@@ -924,6 +1013,9 @@ function form_menufield($attrs) {
  * Other attributes are passed to buildAttributes() for the input tag.
  *
  * @author  Tom N Harris <tnharris@whoopdedo.org>
+ *
+ * @param array $attrs attributes
+ * @return string html
  */
 function form_listboxfield($attrs) {
     $s = '<label';