MDL-30974 form: Checked and updated docblock for form library

lib/form/advcheckbox.php

@@ -1,42 +1,59 @@
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+
+/**
+ * Advanced checkbox type form element
+ *
+ * Contains HTML class for an advcheckbox type form element
+ *
+ * @package   core_form
+ * @copyright 2007 Jamie Pratt <me@jamiep.org>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 require_once('HTML/QuickForm/advcheckbox.php');
 
 /**
- * HTML class for a advcheckbox type element
+ * HTML class for an advcheckbox type element
  *
- * default behavior special for Moodle is to return '0' if not checked
+ * Overloaded {@see HTML_QuickForm_advcheckbox} with default behavior modified for Moodle.
- * '1' for checked.
+ * This will return '0' if not checked and '1' if checked.
  *
- * * @author       Jamie Pratt
+ * @package   core_form
- * @access       public
+ * @category  form
+ * @copyright 2007 Jamie Pratt <me@jamiep.org>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class MoodleQuickForm_advcheckbox extends HTML_QuickForm_advcheckbox{
-    /**
+    /** @var string html for help button, if empty then no help will icon will be dispalyed. */
-     * html for help button, if empty then no help
-     *
-     * @var string
-     */
     var $_helpbutton='';
 
-    /**
+    /** @var string Group to which this checkbox belongs (for select all/select none button) */
-     * Group to which this checkbox belongs (for select all/select none button)
-     * @var string $_group
-     */
     var $_group;
 
     /**
-     * Class constructor
+     * constructor
      *
-     * @param     string    $elementName    (optional)Input field name attribute
+     * @param string $elementName (optional) name of the checkbox
-     * @param     string    $elementLabel   (optional)Input field label
+     * @param string $elementLabel (optional) checkbox label
-     * @param     string    $text           (optional)Text to put after the checkbox
+     * @param string $text (optional) Text to put after the checkbox
-     * @param     mixed     $attributes     (optional)Either a typical HTML attribute string
+     * @param mixed $attributes (optional) Either a typical HTML attribute string
-     *                                      or an associative array
+     *              or an associative array
-     * @param     mixed     $values         (optional)Values to pass if checked or not checked
+     * @param mixed $values (optional) Values to pass if checked or not checked
-     *
-     * @since     1.0
-     * @access    public
-     * @return    void
      */
     function MoodleQuickForm_advcheckbox($elementName=null, $elementLabel=null, $text=null, $attributes=null, $values=null)
     {
@@ -65,29 +82,35 @@ class MoodleQuickForm_advcheckbox extends HTML_QuickForm_advcheckbox{
         }
 
         parent::HTML_QuickForm_advcheckbox($elementName, $elementLabel, $text, $attributes, $values);
-    } //end constructor
+    }
-
 
     /**
      * set html for help button
      *
-     * @access   public
+     * @param array $helpbuttonargs array of arguments to make a help button
-     * @param array $help array of arguments to make a help button
+     * @param string $function (optional)function name get help html
-     * @param string $function function name to call to get html
+     * @deprecated since Moodle 2.0. Please do not call this function any more.
+     * @todo MDL-31047 this api will be removed.
+     * @see MoodleQuickForm::setHelpButton()
      */
     function setHelpButton($helpbuttonargs, $function='helpbutton'){
         debugging('component setHelpButton() is not used any more, please use $mform->setHelpButton() instead');
     }
+
     /**
      * get html for help button
      *
-     * @access   public
+     * @return string html for help button
-     * @return  string html for help button
      */
     function getHelpButton(){
         return $this->_helpbutton;
     }
 
+    /**
+     * Returns HTML for advchecbox form element.
+     *
+     * @return string
+     */
     function toHtml()
     {
         return '<span>' . parent::toHtml() . '</span>';
@@ -96,7 +119,8 @@ class MoodleQuickForm_advcheckbox extends HTML_QuickForm_advcheckbox{
     /**
      * Returns the disabled field. Accessibility: the return "[ ]" from parent
      * class is not acceptable for screenreader users, and we DO want a label.
-     * @return    string
+     *
+     * @return string
      */
     function getFrozenHtml()
     {
@@ -108,6 +132,6 @@ class MoodleQuickForm_advcheckbox extends HTML_QuickForm_advcheckbox{
             $output .= '/>';
         }
         return $output;
-    } //end func getFrozenHtml
+    }
 
 }

lib/form/button.php

@@ -1,63 +1,81 @@
 <?php
-/* vim: set expandtab tabstop=4 shiftwidth=4: */
+// This file is part of Moodle - http://moodle.org/
-// +----------------------------------------------------------------------+
+//
-// | PHP version 4.0                                                      |
+// Moodle is free software: you can redistribute it and/or modify
-// +----------------------------------------------------------------------+
+// it under the terms of the GNU General Public License as published by
-// | Copyright (c) 1997, 1998, 1999, 2000, 2001 The PHP Group             |
+// the Free Software Foundation, either version 3 of the License, or
-// +----------------------------------------------------------------------+
+// (at your option) any later version.
-// | This source file is subject to version 2.0 of the PHP license,       |
+//
-// | that is bundled with this package in the file LICENSE, and is        |
+// Moodle is distributed in the hope that it will be useful,
-// | available at through the world-wide-web at                           |
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
-// | http://www.php.net/license/2_02.txt.                                 |
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-// | If you did not receive a copy of the PHP license and are unable to   |
+// GNU General Public License for more details.
-// | obtain it through the world-wide-web, please send a note to          |
+//
-// | license@php.net so we can mail you a copy immediately.               |
+// You should have received a copy of the GNU General Public License
-// +----------------------------------------------------------------------+
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
-// | Authors: Adam Daniel <adaniel1@eesus.jnj.com>                        |
+
-// |          Bertrand Mansion <bmansion@mamasam.com>                     |
+
-// +----------------------------------------------------------------------+
+/**
+ * Button form element
+ *
+ * Contains HTML class for a button type element
+ *
+ * @package   core_form
+ * @copyright 2007 Jamie Pratt <me@jamiep.org>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 
 require_once("HTML/QuickForm/button.php");
 
 /**
  * HTML class for a button type element
  *
- * @author       Adam Daniel <adaniel1@eesus.jnj.com>
+ * Overloaded {@see HTML_QuickForm_button} to add help button
- * @author       Bertrand Mansion <bmansion@mamasam.com>
+ * 
- * @version      1.1
+ * @package   core_form
- * @since        PHP4.04pl1
+ * @category  form
- * @access       public
+ * @copyright 2007 Jamie Pratt <me@jamiep.org>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class MoodleQuickForm_button extends HTML_QuickForm_button
 {
-    /**
+    /** @var string html for help button, if empty then no help */
-     * html for help button, if empty then no help
-     *
-     * @var string
-     */
     var $_helpbutton='';
+
+    /**
+     * constructor
+     *
+     * @param string $elementName (optional) name for the button
+     * @param string $value (optional) value for the button
+     * @param mixed $attributes (optional) Either a typical HTML attribute string
+     *              or an associative array
+     */
     function MoodleQuickForm_button($elementName=null, $value=null, $attributes=null) {
         parent::HTML_QuickForm_button($elementName, $value, $attributes);
     }
+
     /**
      * set html for help button
      *
-     * @access   public
+     * @param array $helpbuttonargs array of arguments to make a help button
-     * @param array $help array of arguments to make a help button
      * @param string $function function name to call to get html
+     * @deprecated since Moodle 2.0. Please do not call this function any more.
+     * @todo MDL-31047 this api will be removed.
+     * @see MoodleQuickForm::setHelpButton()
      */
     function setHelpButton($helpbuttonargs, $function='helpbutton'){
         debugging('component setHelpButton() is not used any more, please use $mform->setHelpButton() instead');
     }
+
     /**
      * get html for help button
      *
-     * @access   public
+     * @return string html for help button
-     * @return  string html for help button
      */
     function getHelpButton(){
         return $this->_helpbutton;
     }
+
     /**
      * Slightly different container template when frozen.
      *
@@ -70,4 +88,4 @@ class MoodleQuickForm_button extends HTML_QuickForm_button
             return 'default';
         }
     }
-} //end class MoodleQuickForm_button
+}

lib/form/cancel.php

@@ -1,4 +1,30 @@
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+
+/**
+ * Button form element
+ *
+ * Contains HTML class for a button type element
+ *
+ * @package   core_form
+ * @copyright 2007 Jamie Pratt <me@jamiep.org>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 if (!defined('MOODLE_INTERNAL')) {
     die('Direct access to this script is forbidden.');    ///  It must be included from a Moodle page
 }
@@ -7,21 +33,24 @@ global $CFG;
 require_once($CFG->libdir.'/form/submit.php');
 
 /**
- * HTML class for a submit type element
+ * HTML class for a submit cancel type element
  *
- * @author       Jamie Pratt
+ * Overloaded {@see MoodleQuickForm_submit} with default behavior modified to cancel a form.
- * @access       public
+ *
+ * @package   core_form
+ * @category  form
+ * @copyright 2007 Jamie Pratt <me@jamiep.org>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class MoodleQuickForm_cancel extends MoodleQuickForm_submit
 {
-    // {{{ constructor
-
     /**
-     * Class constructor
+     * constructor
      *
-     * @since     1.0
+     * @param string $elementName (optional) name of the checkbox
-     * @access    public
+     * @param string $value (optional) value for the button
-     * @return    void
+     * @param mixed $attributes (optional) Either a typical HTML attribute string
+     *              or an associative array
      */
     function MoodleQuickForm_cancel($elementName=null, $value=null, $attributes=null)
     {
@@ -33,7 +62,16 @@ class MoodleQuickForm_cancel extends MoodleQuickForm_submit
         }
         MoodleQuickForm_submit::MoodleQuickForm_submit($elementName, $value, $attributes);
         $this->updateAttributes(array('onclick'=>'skipClientValidation = true; return true;'));
-    } //end constructor
+    }
+
+    /**
+     * Called by HTML_QuickForm whenever form event is made on this element
+     *
+     * @param string $event Name of event
+     * @param mixed $arg event arguments
+     * @param object $caller calling object
+     * @return bool
+     */
     function onQuickFormEvent($event, $arg, &$caller)
     {
         switch ($event) {
@@ -45,14 +83,23 @@ class MoodleQuickForm_cancel extends MoodleQuickForm_submit
                 break;
         }
         return parent::onQuickFormEvent($event, $arg, $caller);
-    } // end func onQuickFormEvent
+    }
 
+    /**
+     * Returns the value of field without HTML tags
+     *
+     * @return string
+     */
     function getFrozenHtml(){
         return HTML_QuickForm_submit::getFrozenHtml();
     }
 
+    /**
+     * Freeze the element so that only its value is returned
+     *
+     * @return bool
+     */
     function freeze(){
         return HTML_QuickForm_submit::freeze();
     }
-    // }}}
+}
-} //end class MoodleQuickForm_cancel

lib/form/checkbox.php

@@ -1,37 +1,78 @@
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+
+/**
+ * checkbox form element
+ *
+ * Contains HTML class for a checkbox type element
+ *
+ * @package   core_form
+ * @copyright 2007 Jamie Pratt <me@jamiep.org>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 require_once('HTML/QuickForm/checkbox.php');
 
 /**
  * HTML class for a checkbox type element
  *
- * @author       Jamie Pratt
+ * Overloaded {@see HTML_QuickForm_checkbox} to add help button. Also, fixes bug in quickforms
- * @access       public
+ * checkbox, which lets previous set value override submitted value if checkbox is not checked
+ * and no value is submitted
+ *
+ * @package   core_form
+ * @category  form
+ * @copyright 2007 Jamie Pratt <me@jamiep.org>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class MoodleQuickForm_checkbox extends HTML_QuickForm_checkbox{
-    /**
+    /** @var string html for help button, if empty then no help */
-     * html for help button, if empty then no help
-     *
-     * @var string
-     */
     var $_helpbutton='';
+
+    /**
+     * Constructor
+     *
+     * @param string $elementName (optional) name of the checkbox
+     * @param string $elementLabel (optional) checkbox label
+     * @param string $text (optional) Text to put after the checkbox
+     * @param mixed $attributes (optional) Either a typical HTML attribute string
+     *              or an associative array
+     */
     function MoodleQuickForm_checkbox($elementName=null, $elementLabel=null, $text='', $attributes=null) {
         parent::HTML_QuickForm_checkbox($elementName, $elementLabel, $text, $attributes);
     }
+
     /**
      * set html for help button
      *
-     * @access   public
+     * @param array $helpbuttonargs array of arguments to make a help button
-     * @param array $help array of arguments to make a help button
      * @param string $function function name to call to get html
+     * @deprecated since Moodle 2.0. Please do not call this function any more.
+     * @todo MDL-31047 this api will be removed.
+     * @see MoodleQuickForm::setHelpButton()
      */
     function setHelpButton($helpbuttonargs, $function='helpbutton'){
         debugging('component setHelpButton() is not used any more, please use $mform->setHelpButton() instead');
     }
+
     /**
      * get html for help button
      *
-     * @access   public
+     * @return string html for help button
-     * @return  string html for help button
      */
     function getHelpButton(){
         return $this->_helpbutton;
@@ -40,12 +81,10 @@ class MoodleQuickForm_checkbox extends HTML_QuickForm_checkbox{
     /**
      * Called by HTML_QuickForm whenever form event is made on this element
      *
-     * @param     string    $event  Name of event
+     * @param string $event Name of event
-     * @param     mixed     $arg    event arguments
+     * @param mixed $arg event arguments
-     * @param     object    $caller calling object
+     * @param object $caller calling object
-     * @since     1.0
+     * @return bool
-     * @access    public
-     * @return    void
      */
     function onQuickFormEvent($event, $arg, &$caller)
     {
@@ -73,7 +112,13 @@ class MoodleQuickForm_checkbox extends HTML_QuickForm_checkbox{
                 parent::onQuickFormEvent($event, $arg, $caller);
         }
         return true;
-    } // end func onQuickFormEvent
+    }
+
+    /**
+     * Returns HTML for checbox form element.
+     * 
+     * @return string
+     */
     function toHtml()
     {
         return '<span>' . parent::toHtml() . '</span>';
@@ -82,7 +127,8 @@ class MoodleQuickForm_checkbox extends HTML_QuickForm_checkbox{
     /**
      * Returns the disabled field. Accessibility: the return "[ ]" from parent
      * class is not acceptable for screenreader users, and we DO want a label.
-     * @return    string
+     *
+     * @return string
      */
     function getFrozenHtml()
     {
@@ -94,5 +140,5 @@ class MoodleQuickForm_checkbox extends HTML_QuickForm_checkbox{
             $output .= '/>';
         }
         return $output;
-    } //end func getFrozenHtml
+    }
 }

lib/form/dateselector.php

@@ -1,27 +1,29 @@
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
-///////////////////////////////////////////////////////////////////////////
+
-//                                                                       //
+/**
-// NOTICE OF COPYRIGHT                                                   //
+ * Group of date input element
-//                                                                       //
+ *
-// Moodle - Modular Object-Oriented Dynamic Learning Environment         //
+ * Contains class for a group of elements used to input a date.
-//          http://moodle.org                                            //
+ *
-//                                                                       //
+ * @package   core_form
-// Copyright (C) 1999 onwards Martin Dougiamas  http://dougiamas.com     //
+ * @copyright 2007 Jamie Pratt <me@jamiep.org>
-//                                                                       //
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
-// This program is free software; you can redistribute it and/or modify  //
+ */
-// it under the terms of the GNU General Public License as published by  //
-// the Free Software Foundation; either version 2 of the License, or     //
-// (at your option) any later version.                                   //
-//                                                                       //
-// This program is distributed in the hope that it will be useful,       //
-// but WITHOUT ANY WARRANTY; without even the implied warranty of        //
-// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         //
-// GNU General Public License for more details:                          //
-//                                                                       //
-//          http://www.gnu.org/copyleft/gpl.html                         //
-//                                                                       //
-///////////////////////////////////////////////////////////////////////////
 
 global $CFG;
 require_once($CFG->libdir . '/form/group.php');
@@ -32,38 +34,36 @@ require_once($CFG->libdir . '/formslib.php');
  *
  * Emulates moodle print_date_selector function
  *
- * @package formslib
+ * @package   core_form
+ * @category  form
+ * @copyright 2007 Jamie Pratt <me@jamiep.org>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class MoodleQuickForm_date_selector extends MoodleQuickForm_group
 {
     /**
-    * Control the fieldnames for form elements
+     * Control the fieldnames for form elements
-    *
+     * startyear => int start of range of years that can be selected
-    * startyear => integer start of range of years that can be selected
+     * stopyear => int last year that can be selected
-    * stopyear => integer last year that can be selected
+     * timezone => float/string timezone
-    * timezone => float/string timezone
+     * applydst => apply users daylight savings adjustment?
-    * applydst => apply users daylight savings adjustment?
+     * optional => if true, show a checkbox beside the date to turn it on (or off)
-    * optional => if true, show a checkbox beside the date to turn it on (or off)
+     * @var array
-    */
+     */
     protected $_options = array('startyear' => 1970, 'stopyear' => 2020,
             'timezone' => 99, 'applydst' => true, 'optional' => false);
 
-   /**
+   /** @var array These complement separators, they are appended to the resultant HTML */
-    * These complement separators, they are appended to the resultant HTML
-    * @access   private
-    * @var      array
-    */
     protected $_wrap = array('', '');
 
-   /**
+    /**
-    * Class constructor
+     * constructor
-    *
+     *
-    * @access   public
+     * @param string $elementName Element's name
-    * @param    string  Element's name
+     * @param mixed $elementLabel Label(s) for an element
-    * @param    mixed   Label(s) for an element
+     * @param array $options Options to control the element's display
-    * @param    array   Options to control the element's display
+     * @param mixed $attributes Either a typical HTML attribute string or an associative array
-    * @param    mixed   Either a typical HTML attribute string or an associative array
+     */
-    */
     function MoodleQuickForm_date_selector($elementName = null, $elementLabel = null, $options = array(), $attributes = null)
     {
         $this->HTML_QuickForm_element($elementName, $elementLabel, $attributes);
@@ -85,9 +85,11 @@ class MoodleQuickForm_date_selector extends MoodleQuickForm_group
         form_init_date_js();
     }
 
-    // }}}
+    /**
-    // {{{ _createElements()
+     * This will create date group element constisting of day, month and year.
-
+     *
+     * @access private
+     */
     function _createElements()
     {
         $this->_elements = array();
@@ -115,18 +117,13 @@ class MoodleQuickForm_date_selector extends MoodleQuickForm_group
 
     }
 
-    // }}}
-    // {{{ onQuickFormEvent()
-
     /**
      * Called by HTML_QuickForm whenever form event is made on this element
-     *
+     * 
-     * @param     string    $event  Name of event
+     * @param string $event Name of event
-     * @param     mixed     $arg    event arguments
+     * @param mixed $arg event arguments
-     * @param     object    $caller calling object
+     * @param object $caller calling object
-     * @since     1.0
+     * @return bool
-     * @access    public
-     * @return    void
      */
     function onQuickFormEvent($event, $arg, &$caller)
     {
@@ -176,10 +173,13 @@ class MoodleQuickForm_date_selector extends MoodleQuickForm_group
             default:
                 return parent::onQuickFormEvent($event, $arg, $caller);
         }
-    } // end func onQuickFormEvent
+    }
-
-    // {{{ toHtml()
 
+    /**
+     * Returns HTML for advchecbox form element.
+     *
+     * @return string
+     */
     function toHtml()
     {
         include_once('HTML/QuickForm/Renderer/Default.php');
@@ -189,21 +189,23 @@ class MoodleQuickForm_date_selector extends MoodleQuickForm_group
         return $this->_wrap[0] . $renderer->toHtml() . $this->_wrap[1];
     }
 
-    // }}}
+    /**
-    // {{{ accept()
+     * Accepts a renderer
-
+     *
+     * @param HTML_QuickForm_Renderer $renderer An HTML_QuickForm_Renderer object
+     * @param bool $required Whether a group is required
+     * @param string $error An error message associated with a group
+     */
     function accept(&$renderer, $required = false, $error = null)
     {
         $renderer->renderElement($this, $required, $error);
     }
 
-    // }}}
-
     /**
      * Output a timestamp. Give it the name of the group.
      *
-     * @param array $submitValues
+     * @param array $submitValues values submitted.
-     * @param bool $assoc
+     * @param bool $assoc specifies if returned array is associative
      * @return array
      */
     function exportValue(&$submitValues, $assoc = false)
@@ -237,6 +239,4 @@ class MoodleQuickForm_date_selector extends MoodleQuickForm_group
             return null;
         }
     }
-
-    // }}}
 }

lib/form/datetimeselector.php

@@ -1,70 +1,70 @@
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
-///////////////////////////////////////////////////////////////////////////
+
-//                                                                       //
+/**
-// NOTICE OF COPYRIGHT                                                   //
+ * Group of date and time input element
-//                                                                       //
+ *
-// Moodle - Modular Object-Oriented Dynamic Learning Environment         //
+ * Contains class for a group of elements used to input a date and time.
-//          http://moodle.org                                            //
+ *
-//                                                                       //
+ * @package   core_form
-// Copyright (C) 1999 onwards Martin Dougiamas  http://dougiamas.com     //
+ * @copyright 2006 Jamie Pratt <me@jamiep.org>
-//                                                                       //
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
-// This program is free software; you can redistribute it and/or modify  //
+ */
-// it under the terms of the GNU General Public License as published by  //
-// the Free Software Foundation; either version 2 of the License, or     //
-// (at your option) any later version.                                   //
-//                                                                       //
-// This program is distributed in the hope that it will be useful,       //
-// but WITHOUT ANY WARRANTY; without even the implied warranty of        //
-// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         //
-// GNU General Public License for more details:                          //
-//                                                                       //
-//          http://www.gnu.org/copyleft/gpl.html                         //
-//                                                                       //
-///////////////////////////////////////////////////////////////////////////
 
 global $CFG;
 require_once($CFG->libdir . '/form/group.php');
 require_once($CFG->libdir . '/formslib.php');
 
 /**
+ * Element used to input a date and time.
+ *
  * Class for a group of elements used to input a date and time.
  *
- * Emulates moodle print_date_selector function and also allows you to select a time.
+ * @package   core_form
- *
+ * @category  form
- * @package formslib
+ * @copyright 2006 Jamie Pratt <me@jamiep.org>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class MoodleQuickForm_date_time_selector extends MoodleQuickForm_group{
     /**
-    * Options for the element
+     * Options for the element
-    *
+     * startyear => int start of range of years that can be selected
-    * startyear => integer start of range of years that can be selected
+     * stopyear => int last year that can be selected
-    * stopyear => integer last year that can be selected
+     * defaulttime => default time value if the field is currently not set
-    * defaulttime => default time value if the field is currently not set
+     * timezone => float/string timezone
-    * timezone => float/string timezone
+     * applydst => apply users daylight savings adjustment?
-    * applydst => apply users daylight savings adjustment?
+     * step => step to increment minutes by
-    * step     => step to increment minutes by
+     * optional => if true, show a checkbox beside the date to turn it on (or off)
-    * optional => if true, show a checkbox beside the date to turn it on (or off)
+     * @var array
-    */
+     */
     var $_options = array('startyear' => 1970, 'stopyear' => 2020, 'defaulttime' => 0,
                     'timezone' => 99, 'applydst' => true, 'step' => 5, 'optional' => false);
 
-   /**
+    /** @var array These complement separators, they are appended to the resultant HTML */
-    * These complement separators, they are appended to the resultant HTML
-    * @access   private
-    * @var      array
-    */
     var $_wrap = array('', '');
 
-   /**
+    /**
-    * Class constructor
+     * Class constructor
-    *
+     *
-    * @access   public
+     * @param string $elementName Element's name
-    * @param    string  Element's name
+     * @param mixed $elementLabel Label(s) for an element
-    * @param    mixed   Label(s) for an element
+     * @param array $options Options to control the element's display
-    * @param    array   Options to control the element's display
+     * @param mixed $attributes Either a typical HTML attribute string or an associative array
-    * @param    mixed   Either a typical HTML attribute string or an associative array
+     */
-    */
     function MoodleQuickForm_date_time_selector($elementName = null, $elementLabel = null, $options = array(), $attributes = null)
     {
         $this->HTML_QuickForm_element($elementName, $elementLabel, $attributes);
@@ -86,9 +86,11 @@ class MoodleQuickForm_date_time_selector extends MoodleQuickForm_group{
         form_init_date_js();
     }
 
-    // }}}
+    /**
-    // {{{ _createElements()
+     * This will create date group element constisting of day, month and year.
-
+     *
+     * @access private
+     */
     function _createElements()
     {
         $this->_elements = array();
@@ -129,18 +131,13 @@ class MoodleQuickForm_date_time_selector extends MoodleQuickForm_group{
 
     }
 
-    // }}}
-    // {{{ onQuickFormEvent()
-
     /**
      * Called by HTML_QuickForm whenever form event is made on this element
      *
-     * @param     string    $event  Name of event
+     * @param string $event Name of event
-     * @param     mixed     $arg    event arguments
+     * @param mixed $arg event arguments
-     * @param     object    $caller calling object
+     * @param object $caller calling object
-     * @since     1.0
+     * @return bool
-     * @access    public
-     * @return    void
      */
     function onQuickFormEvent($event, $arg, &$caller)
     {
@@ -197,9 +194,11 @@ class MoodleQuickForm_date_time_selector extends MoodleQuickForm_group{
         }
     }
 
-    // }}}
+    /**
-    // {{{ toHtml()
+     * Returns HTML for advchecbox form element.
-
+     *
+     * @return string
+     */
     function toHtml()
     {
         include_once('HTML/QuickForm/Renderer/Default.php');
@@ -209,21 +208,23 @@ class MoodleQuickForm_date_time_selector extends MoodleQuickForm_group{
         return $this->_wrap[0] . $renderer->toHtml() . $this->_wrap[1];
     }
 
-    // }}}
+    /**
-    // {{{ accept()
+     * Accepts a renderer
-
+     *
+     * @param HTML_QuickForm_Renderer $renderer An HTML_QuickForm_Renderer object
+     * @param bool $required Whether a group is required
+     * @param string $error An error message associated with a group
+     */
     function accept(&$renderer, $required = false, $error = null)
     {
         $renderer->renderElement($this, $required, $error);
     }
 
-    // }}}
-
     /**
      * Output a timestamp. Give it the name of the group.
      *
-     * @param array $submitValues
+     * @param array $submitValues values submitted.
-     * @param bool $assoc
+     * @param bool $assoc specifies if returned array is associative
      * @return array
      */
     function exportValue(&$submitValues, $assoc = false)
@@ -261,6 +262,4 @@ class MoodleQuickForm_date_time_selector extends MoodleQuickForm_group{
             return null;
         }
     }
-
-    // }}}
 }

lib/form/duration.php

@@ -1,27 +1,29 @@
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
-///////////////////////////////////////////////////////////////////////////
+
-//                                                                       //
+/**
-// NOTICE OF COPYRIGHT                                                   //
+ * Duration form element
-//                                                                       //
+ *
-// Moodle - Modular Object-Oriented Dynamic Learning Environment         //
+ * Contains class to create length of time for element.
-//          http://moodle.org                                            //
+ *
-//                                                                       //
+ * @package   core_form
-// Copyright (C) 1999 onwards Martin Dougiamas  http://dougiamas.com     //
+ * @copyright 2009 Tim Hunt
-//                                                                       //
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
-// This program is free software; you can redistribute it and/or modify  //
+ */
-// it under the terms of the GNU General Public License as published by  //
-// the Free Software Foundation; either version 2 of the License, or     //
-// (at your option) any later version.                                   //
-//                                                                       //
-// This program is distributed in the hope that it will be useful,       //
-// but WITHOUT ANY WARRANTY; without even the implied warranty of        //
-// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         //
-// GNU General Public License for more details:                          //
-//                                                                       //
-//          http://www.gnu.org/copyleft/gpl.html                         //
-//                                                                       //
-///////////////////////////////////////////////////////////////////////////
 
 global $CFG;
 require_once($CFG->libdir . '/form/group.php');
@@ -29,30 +31,37 @@ require_once($CFG->libdir . '/formslib.php');
 require_once($CFG->libdir . '/form/text.php');
 
 /**
+ * Duration element
+ *
  * HTML class for a length of time. For example, 30 minutes of 4 days. The
  * values returned to PHP is the duration in seconds.
  *
- * @package formslib
+ * @package   core_form
+ * @category  form
+ * @copyright 2009 Tim Hunt
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class MoodleQuickForm_duration extends MoodleQuickForm_group {
    /**
     * Control the fieldnames for form elements
     * optional => if true, show a checkbox beside the element to turn it on (or off)
+    * @var array
     */
    protected $_options = array('optional' => false, 'defaultunit' => 60);
 
+   /** @var array associative array of time units (days, hours, minutes, seconds) */
    private $_units = null;
 
    /**
-    * Class constructor
+    * constructor
     *
-    * @access public
+    * @param string $elementName Element's name
-    * @param  string $elementName Element's name
+    * @param mixed $elementLabel Label(s) for an element
-    * @param  mixed  $elementLabel Label(s) for an element
+    * @param array $options Options to control the element's display. Recognised values are
-    * @param  array  $options Options to control the element's display. Recognised values are
+                   'optional' => true/false - whether to display an 'enabled' checkbox next to the element.
-    *       'optional' => true/false - whether to display an 'enabled' checkbox next to the element.
+                   'defaultunit' => 1|60|3600|86400 - the default unit to display when the time is blank.
-    *       'defaultunit' => 1|60|3600|86400 - the default unit to display when the time is blank. If not specified, minutes is used.
+    *              If not specified, minutes is used.
-    * @param  mixed  $attributes Either a typical HTML attribute string or an associative array
+    * @param mixed $attributes Either a typical HTML attribute string or an associative array
     */
     function MoodleQuickForm_duration($elementName = null, $elementLabel = null, $options = array(), $attributes = null) {
         $this->HTML_QuickForm_element($elementName, $elementLabel, $attributes);
@@ -75,6 +84,8 @@ class MoodleQuickForm_duration extends MoodleQuickForm_group {
     }
 
     /**
+     * Returns time associative array of unit length.
+     *
      * @return array unit length in seconds => string unit name.
      */
     public function get_units() {
@@ -90,9 +101,11 @@ class MoodleQuickForm_duration extends MoodleQuickForm_group {
     }
 
     /**
-     * @param $seconds an amout of time in seconds.
+     * Converts seconds to the best possible time unit. for example 
-     * @return array($number, $unit) Conver an interval to the best possible unit.
+     * 1800 -> array(30, 60) = 30 minutes.
-     *      for example 1800 -> array(30, 60) = 30 minutes.
+     *
+     * @param int $seconds an amout of time in seconds.
+     * @return array associative array ($number => $unit)
      */
     public function seconds_to_unit($seconds) {
         if ($seconds == 0) {
@@ -106,7 +119,9 @@ class MoodleQuickForm_duration extends MoodleQuickForm_group {
         return array($seconds, 1);
     }
 
-    // Override of standard quickforms method.
+    /**
+     * Override of standard quickforms method to create this element.
+     */
     function _createElements() {
         $attributes = $this->getAttributes();
         if (is_null($attributes)) {
@@ -130,7 +145,14 @@ class MoodleQuickForm_duration extends MoodleQuickForm_group {
         }
     }
 
-    // Override of standard quickforms method.
+    /**
+     * Called by HTML_QuickForm whenever form event is made on this element
+     *
+     * @param string $event Name of event
+     * @param mixed $arg event arguments
+     * @param object $caller calling object
+     * @return bool
+     */
     function onQuickFormEvent($event, $arg, $caller) {
         switch ($event) {
             case 'updateValue':
@@ -174,7 +196,11 @@ class MoodleQuickForm_duration extends MoodleQuickForm_group {
         }
     }
 
-    // Override of standard quickforms method.
+    /**
+     * Returns HTML for advchecbox form element.
+     *
+     * @return string
+     */
     function toHtml() {
         include_once('HTML/QuickForm/Renderer/Default.php');
         $renderer = new HTML_QuickForm_Renderer_Default();
@@ -183,7 +209,13 @@ class MoodleQuickForm_duration extends MoodleQuickForm_group {
         return $renderer->toHtml();
     }
 
-    // Override of standard quickforms method.
+    /**
+     * Accepts a renderer
+     *
+     * @param HTML_QuickForm_Renderer $renderer An HTML_QuickForm_Renderer object
+     * @param bool $required Whether a group is required
+     * @param string $error An error message associated with a group
+     */
     function accept($renderer, $required = false, $error = null) {
         $renderer->renderElement($this, $required, $error);
     }
@@ -192,8 +224,8 @@ class MoodleQuickForm_duration extends MoodleQuickForm_group {
      * Output a timestamp. Give it the name of the group.
      * Override of standard quickforms method.
      *
-     * @param array $submitValues
+     * @param  array $submitValues
-     * @param bool $notused Not used.
+     * @param  bool  $notused Not used.
      * @return array field name => value. The value is the time interval in seconds.
      */
     function exportValue($submitValues, $notused = false) {

lib/form/editor.php

@@ -1,4 +1,29 @@
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+
+/**
+ * Editor input element
+ *
+ * Contains class to create preffered editor form element
+ *
+ * @package   core_form
+ * @copyright 2009 Petr Skoda {@link http://skodak.org}
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 
 global $CFG;
 
@@ -6,19 +31,41 @@ require_once('HTML/QuickForm/element.php');
 require_once($CFG->dirroot.'/lib/filelib.php');
 require_once($CFG->dirroot.'/repository/lib.php');
 
-//TODO:
+/**
-//  * locking
+ * Editor element
-//  * freezing
+ *
-//  * ajax format conversion
+ * It creates preffered editor (textbox/TinyMce) form element for the format (Text/HTML) selected. 
-
+ *
+ * @package   core_form
+ * @category  form
+ * @copyright 2009 Petr Skoda {@link http://skodak.org}
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @todo      MDL-29421 element Freezing
+ * @todo      MDL-29426 ajax format conversion
+ */
 class MoodleQuickForm_editor extends HTML_QuickForm_element {
+    /** @var string html for help button, if empty then no help will icon will be dispalyed. */
     public $_helpbutton = '';
 
+    /** @var string defines the type of editor */
     public $_type       = 'editor';
+
+    /** @var array options provided to initalize filepicker */
     protected $_options    = array('subdirs'=>0, 'maxbytes'=>0, 'maxfiles'=>0, 'changeformat'=>0,
                                    'context'=>null, 'noclean'=>0, 'trusttext'=>0);
+
+    /** @var array values for editor */
     protected $_values     = array('text'=>null, 'format'=>null, 'itemid'=>null);
 
+    /**
+     * Constructor
+     *
+     * @param string $elementName (optional) name of the editor
+     * @param string $elementLabel (optional) editor label
+     * @param array $attributes (optional) Either a typical HTML attribute string
+     *              or an associative array
+     * @param array $options set of options to initalize filepicker
+     */
     function MoodleQuickForm_editor($elementName=null, $elementLabel=null, $attributes=null, $options=null) {
         global $CFG, $PAGE;
 
@@ -40,14 +87,29 @@ class MoodleQuickForm_editor extends HTML_QuickForm_element {
         editors_head_setup();
     }
 
+    /**
+     * Sets name of editor
+     *
+     * @param string $name name of the editor
+     */
     function setName($name) {
         $this->updateAttributes(array('name'=>$name));
     }
 
+    /**
+     * Returns name of element
+     *
+     * @return string
+     */
     function getName() {
         return $this->getAttribute('name');
     }
 
+    /**
+     * Updates editor values, if part of $_values
+     * 
+     * @param array $values associative array of values to set
+     */
     function setValue($values) {
         $values = (array)$values;
         foreach ($values as $name=>$value) {
@@ -57,31 +119,66 @@ class MoodleQuickForm_editor extends HTML_QuickForm_element {
         }
     }
 
+    /**
+     * Returns editor values
+     *
+     * @return array 
+     */
     function getValue() {
         return $this->_values;
     }
 
+    /**
+     * Returns maximum file size which can be uploaded
+     *
+     * @return int
+     */
     function getMaxbytes() {
         return $this->_options['maxbytes'];
     }
 
+    /**
+     * Sets maximum file size which can be uploaded
+     *
+     * @param int $maxbytes file size
+     */
     function setMaxbytes($maxbytes) {
         global $CFG;
         $this->_options['maxbytes'] = get_max_upload_file_size($CFG->maxbytes, $maxbytes);
     }
 
+    /**
+     * Returns maximum number of files which can be uploaded
+     *
+     * @return int
+     */
     function getMaxfiles() {
         return $this->_options['maxfiles'];
     }
 
+    /**
+     * Sets maximum number of files which can be uploaded.
+     *
+     * @param int $num number of files
+     */
     function setMaxfiles($num) {
         $this->_options['maxfiles'] = $num;
     }
 
+    /**
+     * Returns true if subdirectoy can be created, else false
+     *
+     * @return bool
+     */
     function getSubdirs() {
         return $this->_options['subdirs'];
     }
 
+    /**
+     * Set option to create sub directory, while uploading  file
+     *
+     * @param bool $allow true if sub directory can be created.
+     */
     function setSubdirs($allow) {
         $this->_options['subdirs'] = $allow;
     }
@@ -96,14 +193,23 @@ class MoodleQuickForm_editor extends HTML_QuickForm_element {
     }
 
     /**
-     * Checks if editor used is tinymce and is required field
+     * Checks if editor used is a required field
      *
-     * @return true if required field.
+     * @return bool true if required field.
      */
     function isRequired() {
         return (isset($this->_options['required']) && $this->_options['required']);
     }
 
+    /**
+     * Sets help button for editor
+     * 
+     * @param mixed $_helpbuttonargs arguments to create help button
+     * @param string $function name of the callback function
+     * @deprecated since Moodle 2.0. Please do not call this function any more.
+     * @todo MDL-31047 this api will be removed.
+     * @see MoodleQuickForm::setHelpButton()
+     */
     function setHelpButton($_helpbuttonargs, $function='_helpbutton') {
         if (!is_array($_helpbuttonargs)) {
             $_helpbuttonargs = array($_helpbuttonargs);
@@ -119,10 +225,20 @@ class MoodleQuickForm_editor extends HTML_QuickForm_element {
         $this->_helpbutton=call_user_func_array($function, $_helpbuttonargs);
     }
 
+    /**
+     * Returns html for help button.
+     *
+     * @return string html for help button
+     */
     function getHelpButton() {
         return $this->_helpbutton;
     }
 
+    /**
+     * Returns type of editor element
+     *
+     * @return string
+     */
     function getElementTemplateType() {
         if ($this->_flagFrozen){
             return 'nodisplay';
@@ -131,6 +247,11 @@ class MoodleQuickForm_editor extends HTML_QuickForm_element {
         }
     }
 
+    /**
+     * Returns HTML for editor form element.
+     *
+     * @return string
+     */
     function toHtml() {
         global $CFG, $PAGE;
         require_once($CFG->dirroot.'/repository/lib.php');
@@ -285,4 +406,4 @@ class MoodleQuickForm_editor extends HTML_QuickForm_element {
 
         return '';
     }
-}
+}

lib/form/file.php

@@ -1,19 +1,57 @@
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+
+/**
+ * File type form element
+ *
+ * Contains HTML class for a file type form element
+ *
+ * @package   core_form
+ * @copyright 2007 Jamie Pratt <me@jamiep.org>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 require_once('HTML/QuickForm/file.php');
 
 /**
+ * file element 
+ *
  * HTML class for a form element to upload a file
  *
- * @author       Jamie Pratt
+ * @package    core_form
- * @access       public
+ * @deprecated since Moodle 2.0 Please do not use this form element.
+ * @todo       MDL-31294 remove this element
+ * @see        MoodleQuickForm_filepicker
+ * @see        MoodleQuickForm_filemanager
+ * @copyright  2007 Jamie Pratt <me@jamiep.org>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class MoodleQuickForm_file extends HTML_QuickForm_file{
-    /**
+    /** @var string html for help button, if empty then no help */
-     * html for help button, if empty then no help
-     *
-     * @var string
-     */
     var $_helpbutton='';
+
+    /**
+     * Constructor
+     *
+     * @param string $elementName (optional) name of the editor
+     * @param string $elementLabel (optional) editor label
+     * @param array $attributes (optional) Either a typical HTML attribute string
+     *              or an associative array
+     */
     function MoodleQuickForm_file($elementName=null, $elementLabel=null, $attributes=null) {
         debugging('file forms element is deprecated, please use new filepicker instead');
         parent::HTML_QuickForm_file($elementName, $elementLabel, $attributes);
@@ -21,19 +59,17 @@ class MoodleQuickForm_file extends HTML_QuickForm_file{
     /**
      * set html for help button
      *
-     * @access   public
+     * @param array $helpbuttonargs array of arguments to make a help button
-     * @param array $help array of arguments to make a help button
      * @param string $function function name to call to get html
+     * @deprecated since Moodle 2.0. Please do not call this function any more.
+     * @todo MDL-31047 this api will be removed.
+     * @see MoodleQuickForm::setHelpButton()
      */
     function setHelpButton($helpbuttonargs, $function='helpbutton'){
         debugging('component setHelpButton() is not used any more, please use $mform->setHelpButton() instead');
     }
     /**
      * set html for help button
-     *
-     * @access   public
-     * @param array $help array of arguments to make a help button
-     * @param string $function function name to call to get html
      */
     function getHelpButton(){
         return $this->_helpbutton;
@@ -41,6 +77,11 @@ class MoodleQuickForm_file extends HTML_QuickForm_file{
 
     /**
      * Override createElement event to add max files
+     *
+     * @param string $event Name of event
+     * @param mixed $arg event arguments
+     * @param object $caller calling object
+     * @return bool
      */
     function onQuickFormEvent($event, $arg, &$caller)
     {
@@ -50,7 +91,8 @@ class MoodleQuickForm_file extends HTML_QuickForm_file{
             return true;
         }
         return parent::onQuickFormEvent($event, $arg, $caller);
-    } // end func onQuickFormEvent
+    }
+
     /**
      * Slightly different container template when frozen.
      *
@@ -64,4 +106,4 @@ class MoodleQuickForm_file extends HTML_QuickForm_file{
         }
     }
 
-}
+}

lib/form/filemanager.php

@@ -14,13 +14,15 @@
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+
 /**
- * File manager
+ * FileManager form element
  *
- * @package    moodlecore
+ * Contains HTML class for a filemanager form element
- * @subpackage file
+ *
- * @copyright  1999 onwards Dongsheng Cai <dongsheng@moodle.com>
+ * @package   core_form
- * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @copyright 2009 Dongsheng Cai <dongsheng@moodle.com>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 global $CFG;
@@ -29,10 +31,31 @@ require_once('HTML/QuickForm/element.php');
 require_once($CFG->dirroot.'/lib/filelib.php');
 require_once($CFG->dirroot.'/repository/lib.php');
 
+/**
+ * Filemanager form element
+ *
+ * FilemaneManager lets user to upload/manage multiple files
+ * @package   core_form
+ * @category  form
+ * @copyright 2009 Dongsheng Cai <dongsheng@moodle.com>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 
+ */
 class MoodleQuickForm_filemanager extends HTML_QuickForm_element {
+    /** @var string html for help button, if empty then no help will icon will be dispalyed. */
     public $_helpbutton = '';
+
+    /** @var array options provided to initalize filemanager */
     protected $_options    = array('mainfile'=>'', 'subdirs'=>1, 'maxbytes'=>-1, 'maxfiles'=>-1, 'accepted_types'=>'*', 'return_types'=>FILE_INTERNAL);
 
+    /**
+     * Constructor
+     *
+     * @param string $elementName (optional) name of the filemanager
+     * @param string $elementLabel (optional) filemanager label
+     * @param array $attributes (optional) Either a typical HTML attribute string
+     *              or an associative array
+     * @param array $options set of options to initalize filemanager
+     */
     function MoodleQuickForm_filemanager($elementName=null, $elementLabel=null, $attributes=null, $options=null) {
         global $CFG, $PAGE;
 
@@ -49,55 +72,124 @@ class MoodleQuickForm_filemanager extends HTML_QuickForm_element {
         parent::HTML_QuickForm_element($elementName, $elementLabel, $attributes);
     }
 
+    /**
+     * Sets name of filemanager
+     *
+     * @param string $name name of the filemanager
+     */
     function setName($name) {
         $this->updateAttributes(array('name'=>$name));
     }
 
+    /**
+     * Returns name of filemanager
+     *
+     * @return string
+     */
     function getName() {
         return $this->getAttribute('name');
     }
 
+    /**
+     * Updates filemanager attribute value
+     * 
+     * @param string $value value to set
+     */
     function setValue($value) {
         $this->updateAttributes(array('value'=>$value));
     }
 
+    /**
+     * Returns filemanager attribute value
+     *
+     * @return string
+     */
     function getValue() {
         return $this->getAttribute('value');
     }
 
+    /**
+     * Returns maximum file size which can be uploaded
+     *
+     * @return int
+     */
     function getMaxbytes() {
         return $this->_options['maxbytes'];
     }
 
+    /**
+     * Sets maximum file size which can be uploaded
+     *
+     * @param int $maxbytes file size
+     */
     function setMaxbytes($maxbytes) {
         global $CFG;
         $this->_options['maxbytes'] = get_max_upload_file_size($CFG->maxbytes, $maxbytes);
     }
 
+    /**
+     * Returns true if subdirectoy can be created, else false
+     *
+     * @return bool
+     */
     function getSubdirs() {
         return $this->_options['subdirs'];
     }
 
+    /**
+     * Set option to create sub directory, while uploading  file
+     *
+     * @param bool $allow true if sub directory can be created.
+     */
     function setSubdirs($allow) {
         $this->_options['subdirs'] = $allow;
     }
 
+    /**
+     * Returns maximum number of files which can be uploaded
+     *
+     * @return int
+     */
     function getMaxfiles() {
         return $this->_options['maxfiles'];
     }
 
+    /**
+     * Sets maximum number of files which can be uploaded.
+     *
+     * @param int $num number of files
+     */
     function setMaxfiles($num) {
         $this->_options['maxfiles'] = $num;
     }
 
+    /**
+     * Sets help button for filemanager
+     * 
+     * @param mixed $helpbuttonargs arguments to create help button
+     * @param string $function name of the callback function
+     * @deprecated since Moodle 2.0. Please do not call this function any more.
+     * @todo MDL-31047 this api will be removed.
+     * @see MoodleQuickForm::setHelpButton()
+     */
     function setHelpButton($helpbuttonargs, $function='helpbutton'){
         debugging('component setHelpButton() is not used any more, please use $mform->setHelpButton() instead');
     }
 
+    /**
+     * Returns html for help button.
+     *
+     * @return string html for help button
+     */
     function getHelpButton() {
         return $this->_helpbutton;
     }
 
+    /**
+     * Returns type of filemanager element
+     *
+     * @return string
+     */
     function getElementTemplateType() {
         if ($this->_flagFrozen){
             return 'nodisplay';
@@ -106,6 +198,11 @@ class MoodleQuickForm_filemanager extends HTML_QuickForm_element {
         }
     }
 
+    /**
+     * Returns HTML for filemanager form element.
+     *
+     * @return string
+     */
     function toHtml() {
         global $CFG, $USER, $COURSE, $PAGE, $OUTPUT;
         require_once("$CFG->dirroot/repository/lib.php");
@@ -159,19 +256,25 @@ class MoodleQuickForm_filemanager extends HTML_QuickForm_element {
     }
 }
 
-
-
 /**
  * Data structure representing a file manager.
  *
+ * This class defines the data structure for file mnager
+ *
+ * @package   core_form
  * @copyright 2010 Dongsheng Cai
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since     Moodle 2.0
+ * @todo      do not use this abstraction (skodak)
  */
 class form_filemanaer_x {
-    //TODO: do not use this abstraction (skodak)
+    /** @var stdClass $options options for filemanager */
-
     public $options;
+
+    /**
+     * Constructor
+     *
+     * @param stdClass $options options for filemanager
+     */
     public function __construct(stdClass $options) {
         global $CFG, $USER, $PAGE;
         require_once($CFG->dirroot. '/repository/lib.php');

lib/form/filepicker.php

@@ -1,4 +1,29 @@
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+
+/**
+ * Filepicker form element
+ *
+ * Contains HTML class for a single filepicker form element
+ *
+ * @package   core_form
+ * @copyright 2009 Dongsheng Cai <dongsheng@moodle.com>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 
 global $CFG;
 
@@ -6,17 +31,31 @@ require_once("HTML/QuickForm/button.php");
 require_once($CFG->dirroot.'/repository/lib.php');
 
 /**
+ * Filepicker form element
+ *
  * HTML class for a single filepicker element (based on button)
  *
- * @author       Moodle.com
+ * @package   core_form
- * @version      1.0
+ * @category  form
- * @since        Moodle 2.0
+ * @copyright 2009 Dongsheng Cai <dongsheng@moodle.com>
- * @access       public
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later 
  */
 class MoodleQuickForm_filepicker extends HTML_QuickForm_input {
+    /** @var string html for help button, if empty then no help will icon will be dispalyed. */
     public $_helpbutton = '';
+
+    /** @var array options provided to initalize filemanager */
     protected $_options    = array('maxbytes'=>0, 'accepted_types'=>'*', 'return_types'=>FILE_INTERNAL);
 
+    /**
+     * Constructor
+     *
+     * @param string $elementName (optional) name of the filepicker
+     * @param string $elementLabel (optional) filepicker label
+     * @param array $attributes (optional) Either a typical HTML attribute string
+     *              or an associative array
+     * @param array $options set of options to initalize filepicker
+     */
     function MoodleQuickForm_filepicker($elementName=null, $elementLabel=null, $attributes=null, $options=null) {
         global $CFG;
 
@@ -33,14 +72,33 @@ class MoodleQuickForm_filepicker extends HTML_QuickForm_input {
         parent::HTML_QuickForm_input($elementName, $elementLabel, $attributes);
     }
 
+    /**
+     * Sets help button for filepicker
+     * 
+     * @param mixed $helpbuttonargs arguments to create help button
+     * @param string $function name of the callback function
+     * @deprecated since Moodle 2.0. Please do not call this function any more.
+     * @todo MDL-31047 this api will be removed.
+     * @see MoodleQuickForm::setHelpButton()
+     */
     function setHelpButton($helpbuttonargs, $function='helpbutton') {
         debugging('component setHelpButton() is not used any more, please use $mform->setHelpButton() instead');
     }
 
+    /**
+     * Returns html for help button.
+     *
+     * @return string html for help button
+     */
     function getHelpButton() {
         return $this->_helpbutton;
     }
 
+    /**
+     * Returns type of filepicker element
+     *
+     * @return string
+     */
     function getElementTemplateType() {
         if ($this->_flagFrozen){
             return 'nodisplay';
@@ -49,6 +107,11 @@ class MoodleQuickForm_filepicker extends HTML_QuickForm_input {
         }
     }
 
+    /**
+     * Returns HTML for filepicker form element.
+     *
+     * @return string
+     */
     function toHtml() {
         global $CFG, $COURSE, $USER, $PAGE, $OUTPUT;
         $id     = $this->_attributes['id'];
@@ -111,6 +174,13 @@ class MoodleQuickForm_filepicker extends HTML_QuickForm_input {
         return $html;
     }
 
+    /**
+     * export uploaded file
+     *
+     * @param array $submitValues values submitted.
+     * @param bool $assoc specifies if returned array is associative
+     * @return array
+     */
     function exportValue(&$submitValues, $assoc = false) {
         global $USER;
 

lib/form/format.php

@@ -1,25 +1,55 @@
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+
+/**
+ * editor format form element
+ *
+ * Contains HTML class for a editor format drop down element
+ *
+ * @package    core_form
+ * @copyright  2007 Jamie Pratt <me@jamiep.org>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 global $CFG;
 require_once "$CFG->libdir/form/select.php";
 
 /**
- * HTML class for a editor format drop down element
+ * editor format form element
  *
- * @author       Jamie Pratt
+ * HTML class for a editor format drop down element
- * @access       public
+ * 
+ * @package    core_form
+ * @copyright  2007 Jamie Pratt <me@jamiep.org>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @deprecated since Moodle 2.0 Please do not use this form element.
+ * @todo       MDL-31294, remove this element
+ * @see        MoodleQuickForm_editor
  */
 class MoodleQuickForm_format extends MoodleQuickForm_select{
 
     /**
      * Class constructor
      *
-     * @param     string    Select name attribute
+     * @param string $elementName Select name attribute
-     * @param     mixed     Label(s) for the select
+     * @param mixed $elementLabel Label(s) for the select
-     * @param     mixed     Either a typical HTML attribute string or an associative array
+     * @param mixed $attributes Either a typical HTML attribute string or an associative array
-     * @param     mixed     Either a string returned from can_use_html_editor() or false for no html editor
+     * @param mixed $useHtmlEditor Either a string returned from can_use_html_editor() or false for no html editor
-     *                      default 'detect' tells element to use html editor if it is available.
+     *              default 'detect' tells element to use html editor if it is available.
-     * @access    public
-     * @return    void
      */
     function MoodleQuickForm_format($elementName=null, $elementLabel=null, $attributes=null, $useHtmlEditor=null)
     {

lib/form/grading.php

@@ -1,5 +1,4 @@
 <?php
-
 // This file is part of Moodle - http://moodle.org/
 //
 // Moodle is free software: you can redistribute it and/or modify
@@ -15,11 +14,15 @@
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+
 /**
+ * Advance grading form element
+ *
  * Element-container for advanced grading custom input
  *
- * @copyright  2011 Marina Glancy
+ * @package   core_form
- * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @copyright 2011 Marina Glancy
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 global $CFG;
@@ -31,36 +34,32 @@ if (class_exists('HTML_QuickForm')) {
 }
 
 /**
+ * Advance grading form element
+ *
  * HTML class for a grading element. This is a wrapper for advanced grading plugins.
  * When adding the 'grading' element to the form, developer must pass an object of
  * class gradingform_instance as $attributes['gradinginstance']. Otherwise an exception will be
  * thrown.
  * This object is responsible for implementing functions to render element html and validate it
  *
- * @author       Marina Glancy
+ * @package   core_form
- * @access       public
+ * @category  form
+ * @copyright 2011 Marina Glancy
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class MoodleQuickForm_grading extends HTML_QuickForm_input{
-    /**
+    /** @var string html for help button, if empty then no help */
-     * html for help button, if empty then no help
-     *
-     * @var string
-     */
     var $_helpbutton='';
 
-    /**
+    /** @var array Stores attributes passed to the element */
-     * Stores attributes passed to the element
-     * @var array
-     */
     private $gradingattributes;
 
     /**
      * Class constructor
      *
-     * @param string $elementName   Input field name attribute
+     * @param string $elementName Input field name attribute
-     * @param mixed $elementLabel   Label(s) for the input field
+     * @param mixed $elementLabel Label(s) for the input field
-     * @param mixed $attributes     Either a typical HTML attribute string or an associative array
+     * @param mixed $attributes Either a typical HTML attribute string or an associative array
-     * @return void
      */
     public function MoodleQuickForm_grading($elementName=null, $elementLabel=null, $attributes=null) {
         parent::HTML_QuickForm_input($elementName, $elementLabel, $attributes);
@@ -83,7 +82,7 @@ class MoodleQuickForm_grading extends HTML_QuickForm_input{
     /**
      * Returns the input field in HTML
      *
-     * @return    string
+     * @return string
      */
     public function toHtml(){
         global $PAGE;
@@ -93,9 +92,11 @@ class MoodleQuickForm_grading extends HTML_QuickForm_input{
     /**
      * set html for help button
      *
-     * @access   public
+     * @param array $helpbuttonargs array of arguments to make a help button
-     * @param array $help array of arguments to make a help button
      * @param string $function function name to call to get html
+     * @deprecated since Moodle 2.0. Please do not call this function any more.
+     * @todo MDL-31047 this api will be removed.
+     * @see MoodleQuickForm::setHelpButton()
      */
     public function setHelpButton($helpbuttonargs, $function='helpbutton'){
         debugging('component setHelpButton() is not used any more, please use $mform->setHelpButton() instead');
@@ -104,8 +105,7 @@ class MoodleQuickForm_grading extends HTML_QuickForm_input{
     /**
      * get html for help button
      *
-     * @access   public
+     * @return string html for help button
-     * @return  string html for help button
      */
     public function getHelpButton(){
         return $this->_helpbutton;
@@ -126,11 +126,11 @@ class MoodleQuickForm_grading extends HTML_QuickForm_input{
      * Adds necessary rules to the element and checks that coorenct instance of gradingform_instance
      * is passed in attributes
      *
-     * @param     string    $event  Name of event
+     * @param string $event Name of event
-     * @param     mixed     $arg    event arguments
+     * @param mixed $arg event arguments
-     * @param     object    $caller calling object
+     * @param object $caller calling object
-     * @return    void
+     * @return bool
-     * @throws    moodle_exception
+     * @throws moodle_exception
      */
     public function onQuickFormEvent($event, $arg, &$caller) {
         if ($event == 'createElement') {
@@ -151,8 +151,9 @@ class MoodleQuickForm_grading extends HTML_QuickForm_input{
      * Function registered as rule for this element and is called when this element is being validated.
      * This is a wrapper to pass the validation to the method gradingform_instance::validate_grading_element
      *
-     * @param mixed $elementValue
+     * @param mixed $elementValue value of element to be validated
-     * @param array $attributes
+     * @param array $attributes element attributes
+     * @return MoodleQuickForm_grading
      */
     static function _validate($elementValue, $attributes = null) {
         return $attributes['gradinginstance']->validate_grading_element($elementValue);

lib/form/group.php

@@ -1,47 +1,87 @@
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+
+/**
+ * Form element group
+ *
+ * Contains HTML class for group form element
+ *
+ * @package   core_form
+ * @copyright 2007 Jamie Pratt <me@jamiep.org>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 require_once("HTML/QuickForm/group.php");
 
 /**
  * HTML class for a form element group
  *
- * @author       Adam Daniel <adaniel1@eesus.jnj.com>
+ * Overloaded {@see HTML_QuickForm_group} with default behavior modified for Moodle.
- * @author       Bertrand Mansion <bmansion@mamasam.com>
+ *
- * @version      1.0
+ * @package   core_form
- * @since        PHP4.04pl1
+ * @category  form
- * @access       public
+ * @copyright 2007 Jamie Pratt <me@jamiep.org>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class MoodleQuickForm_group extends HTML_QuickForm_group{
-    /**
+    /** @var string html for help button, if empty then no help */
-     * html for help button, if empty then no help
-     *
-     * @var string
-     */
     var $_helpbutton='';
+
+    /**
+     * constructor
+     *
+     * @param string $elementName (optional) name of the group
+     * @param string $elementLabel (optional) group label
+     * @param array $elements (optional) array of HTML_QuickForm_element elements to group
+     * @param string $separator (optional) string to seperate elements.
+     * @param string $appendName (optional) string to appened to grouped elements.
+     */
     function MoodleQuickForm_group($elementName=null, $elementLabel=null, $elements=null, $separator=null, $appendName = true) {
         parent::HTML_QuickForm_group($elementName, $elementLabel, $elements, $separator, $appendName);
     }
-    //would cause problems with client side validation so will leave for now
+
+    /** @var string template type, would cause problems with client side validation so will leave for now */
     //var $_elementTemplateType='fieldset';
+
     /**
      * set html for help button
      *
-     * @access   public
+     * @param array $helpbuttonargs array of arguments to make a help button
-     * @param array $help array of arguments to make a help button
      * @param string $function function name to call to get html
+     * @deprecated since Moodle 2.0. Please do not call this function any more.
+     * @todo MDL-31047 this api will be removed.
+     * @see MoodleQuickForm::setHelpButton()
      */
     function setHelpButton($helpbuttonargs, $function='helpbutton'){
         debugging('component setHelpButton() is not used any more, please use $mform->setHelpButton() instead');
     }
+
     /**
      * set html for help button
-     *
-     * @access   public
-     * @param array $help array of arguments to make a help button
-     * @param string $function function name to call to get html
      */
     function getHelpButton(){
         return $this->_helpbutton;
     }
+
+    /**
+     * Returns element template, nodisplay/static/fieldset
+     *
+     * @return string
+     */
     function getElementTemplateType(){
         if ($this->_flagFrozen){
             if ($this->getGroupType() == 'submit'){
@@ -54,6 +94,11 @@ class MoodleQuickForm_group extends HTML_QuickForm_group{
         }
     }
 
+    /**
+     * Sets the grouped elements and hides label
+     *
+     * @param array $elements
+     */
     function setElements($elements){
         parent::setElements($elements);
         foreach ($this->_elements as $element){

lib/form/header.php

@@ -1,57 +1,87 @@
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+
+/**
+ * Header form element
+ *
+ * Contains a pseudo-element used for adding headers to form
+ *
+ * @package   core_form
+ * @copyright 2007 Jamie Pratt <me@jamiep.org>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 
 require_once 'HTML/QuickForm/header.php';
 
 /**
+ * Header form element
+ *
  * A pseudo-element used for adding headers to form
  *
+ * @package   core_form
+ * @category  form
+ * @copyright 2007 Jamie Pratt <me@jamiep.org>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class MoodleQuickForm_header extends HTML_QuickForm_header
 {
-    /**
+    /** @var string html for help button, if empty then no help */
-     * html for help button, if empty then no help
-     *
-     * @var string
-     */
     var $_helpbutton='';
 
+    /**
+     * constructor
+     *
+     * @param string $elementName name of the header element
+     * @param string $text text displayed in header element
+     */
     function MoodleQuickForm_header($elementName = null, $text = null) {
         parent::HTML_QuickForm_header($elementName, $text);
     }
 
-    // {{{ accept()
-
    /**
     * Accepts a renderer
     *
-    * @param object     An HTML_QuickForm_Renderer object
+    * @param HTML_QuickForm_Renderer $renderer a HTML_QuickForm_Renderer object
-    * @access public
-    * @return void
     */
     function accept(&$renderer)
     {
         $this->_text .= $this->getHelpButton();
         $renderer->renderHeader($this);
-    } // end func accept
+    }
 
-    // }}}
     /**
      * set html for help button
      *
-     * @access   public
+     * @param array $helpbuttonargs array of arguments to make a help button
-     * @param array $help array of arguments to make a help button
      * @param string $function function name to call to get html
+     * @deprecated since Moodle 2.0. Please do not call this function any more.
+     * @todo MDL-31047 this api will be removed.
+     * @see MoodleQuickForm::setHelpButton()
      */
     function setHelpButton($helpbuttonargs, $function='helpbutton'){
         debugging('component setHelpButton() is not used any more, please use $mform->setHelpButton() instead');
     }
+
     /**
      * get html for help button
      *
-     * @access   public
+     * @return string html for help button
-     * @return  string html for help button
      */
     function getHelpButton(){
         return $this->_helpbutton;
     }
-} //end class MoodleQuickForm_header
+}

lib/form/hidden.php

@@ -1,20 +1,54 @@
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+
+/**
+ * Hidden type form element
+ *
+ * Contains HTML class for a hidden type element
+ *
+ * @package   core_form
+ * @copyright 2006 Jamie Pratt <me@jamiep.org>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 require_once('HTML/QuickForm/hidden.php');
 
 /**
+ * Hidden type form element
+ *
  * HTML class for a hidden type element
  *
- * @author       Jamie Pratt
+ * @package   core_form
- * @access       public
+ * @category  form
+ * @copyright 2006 Jamie Pratt <me@jamiep.org>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class MoodleQuickForm_hidden extends HTML_QuickForm_hidden{
-    /**
+    /** @var string html for help button, if empty then no help */
-     * html for help button, if empty then no help
-     *
-     * @var string
-     */
     var $_helpbutton='';
 
+    /**
+     * Constructor
+     *
+     * @param string $elementName (optional) name of the hidden element
+     * @param string $value (optional) value of the element
+     * @param mixed  $attributes (optional) Either a typical HTML attribute string
+     *               or an associative array
+     */
     function MoodleQuickForm_hidden($elementName=null, $value='', $attributes=null) {
         parent::HTML_QuickForm_hidden($elementName, $value, $attributes);
     }
@@ -22,18 +56,20 @@ class MoodleQuickForm_hidden extends HTML_QuickForm_hidden{
     /**
      * set html for help button
      *
-     * @access   public
+     * @param array $helpbuttonargs array of arguments to make a help button
-     * @param array $help array of arguments to make a help button
      * @param string $function function name to call to get html
+     * @deprecated since Moodle 2.0. Please do not call this function any more.
+     * @todo MDL-31047 this api will be removed.
+     * @see MoodleQuickForm::setHelpButton()
      */
     function setHelpButton($helpbuttonargs, $function='helpbutton'){
 
     }
+
     /**
      * get html for help button
      *
-     * @access   public
+     * @return string html for help button
-     * @return  string html for help button
      */
     function getHelpButton(){
         return '';

lib/form/htmleditor.php

@@ -1,17 +1,62 @@
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+
+/**
+ * htmleditor type form element
+ *
+ * Contains HTML class for htmleditor type element
+ *
+ * @package   core_form
+ * @copyright 2006 Jamie Pratt <me@jamiep.org>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 global $CFG;
 require_once("$CFG->libdir/form/textarea.php");
 
 /**
+ * htmleditor type form element
+ *
  * HTML class for htmleditor type element
  *
- * @author       Jamie Pratt
+ * @package   core_form
- * @access       public
+ * @category  form
+ * @copyright 2006 Jamie Pratt <me@jamiep.org>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class MoodleQuickForm_htmleditor extends MoodleQuickForm_textarea{
+    /** @var string defines the type of editor */
     var $_type;
+
+    /** @var bool Does the user want and can edit using rich text html editor */
     var $_canUseHtmlEditor;
+
+    /** @var array default options for html editor, which can be overridden */
     var $_options=array('canUseHtmlEditor'=>'detect','rows'=>10, 'cols'=>45, 'width'=>0,'height'=>0);
+
+    /**
+     * Constructor
+     *
+     * @param string $elementName (optional) name of the html editor
+     * @param string $elementLabel (optional) editor label
+     * @param array $options set of options to create html editor
+     * @param array $attributes (optional) Either a typical HTML attribute string
+     *              or an associative array
+     */
     function MoodleQuickForm_htmleditor($elementName=null, $elementLabel=null, $options=array(), $attributes=null){
         parent::MoodleQuickForm_textarea($elementName, $elementLabel, $attributes);
         // set the options, do not bother setting bogus ones
@@ -39,17 +84,25 @@ class MoodleQuickForm_htmleditor extends MoodleQuickForm_textarea{
 
         editors_head_setup();
     }
+
     /**
      * set html for help button
      *
-     * @access   public
+     * @param array $helpbuttonargs array of arguments to make a help button
-     * @param array $help array of arguments to make a help button
      * @param string $function function name to call to get html
+     * @deprecated since Moodle 2.0. Please do not call this function any more.
+     * @todo MDL-31047 this api will be removed.
+     * @see MoodleQuickForm::setHelpButton()
      */
     function setHelpButton($helpbuttonargs, $function='helpbutton'){
         debugging('component setHelpButton() is not used any more, please use $mform->setHelpButton() instead');
     }
 
+    /**
+     * Returns the input field in HTML
+     *
+     * @return string
+     */
     function toHtml(){
         //if ($this->_canUseHtmlEditor && !$this->_flagFrozen){
         //    $script = '';
@@ -71,17 +124,16 @@ class MoodleQuickForm_htmleditor extends MoodleQuickForm_textarea{
                                     true,
                                     $this->getAttribute('id'));
         }
-    } //end func toHtml
+    }
 
     /**
      * What to display when element is frozen.
      *
-     * @access    public
+     * @return string
-     * @return    string
      */
     function getFrozenHtml()
     {
         $html = format_text($this->getValue());
         return $html . $this->_getPersistantData();
-    } //end func getFrozenHtml
+    }
 }

lib/form/modgrade.php

@@ -1,27 +1,57 @@
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+
+/**
+ * Drop down form element to select the grade
+ *
+ * Contains HTML class for a drop down element to select the grade for an activity,
+ * used in mod update form
+ *
+ * @package   core_form
+ * @copyright 2006 Jamie Pratt <me@jamiep.org>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 global $CFG;
 require_once "$CFG->libdir/form/select.php";
 
 /**
+ * Drop down form element to select the grade
+ *
  * HTML class for a drop down element to select the grade for an activity,
  * used in mod update form
  *
- * @author       Jamie Pratt
+ * @package   core_form
- * @access       public
+ * @category  form
+ * @copyright 2006 Jamie Pratt <me@jamiep.org>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class MoodleQuickForm_modgrade extends MoodleQuickForm_select{
 
+    /** @var bool if true the hides grade */
     var $_hidenograde = false;
 
     /**
      * Class constructor
      *
-     * @param     string    Select name attribute
+     * @param string $elementName (optional) name attribute
-     * @param     mixed     Label(s) for the select
+     * @param mixed $elementLabel (optional) Label for the drop down
-     * @param     mixed     Either a typical HTML attribute string or an associative array
+     * @param mixed $attributes (optional) Either a typical HTML attribute string or an associative array
-     * @param     mixed     $options ignored
+     * @param mixed $hidenograde (optional) hide grade
-     * @access    public
-     * @return    void
      */
     function MoodleQuickForm_modgrade($elementName=null, $elementLabel=null, $attributes=null, $hidenograde=false)
     {
@@ -29,17 +59,15 @@ class MoodleQuickForm_modgrade extends MoodleQuickForm_select{
         $this->_type = 'modgrade';
         $this->_hidenograde = $hidenograde;
 
-    } //end constructor
+    }
 
     /**
      * Called by HTML_QuickForm whenever form event is made on this element
      *
-     * @param     string    $event  Name of event
+     * @param string $event Name of event
-     * @param     mixed     $arg    event arguments
+     * @param mixed $arg event arguments
-     * @param     object    $caller calling object
+     * @param object $caller calling object
-     * @since     1.0
+     * @return mixed
-     * @access    public
-     * @return    mixed
      */
     function onQuickFormEvent($event, $arg, &$caller)
     {

lib/form/modvisible.php

@@ -1,24 +1,52 @@
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+
+/**
+ * Drop down form element to select visibility in an activity mod update form
+ *
+ * Contains HTML class for a drop down element to select visibility in an activity mod update form
+ *
+ * @package   core_form
+ * @copyright 2006 Jamie Pratt <me@jamiep.org>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 global $CFG;
 require_once "$CFG->libdir/form/select.php";
 
 /**
+ * Drop down form element to select visibility in an activity mod update form
+ *
  * HTML class for a drop down element to select visibility in an activity mod update form
  *
- * @author       Jamie Pratt
+ * @package   core_form
- * @access       public
+ * @category  form
+ * @copyright 2006 Jamie Pratt <me@jamiep.org>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class MoodleQuickForm_modvisible extends MoodleQuickForm_select{
 
     /**
      * Class constructor
      *
-     * @param     string    $elementName Select name attribute
+     * @param string $elementName Select name attribute
-     * @param     mixed     $elementLabel Label(s) for the select
+     * @param mixed $elementLabel Label(s) for the select
-     * @param     mixed     $attributes Either a typical HTML attribute string or an associative array
+     * @param mixed $attributes Either a typical HTML attribute string or an associative array
-     * @param     array     $options ignored
+     * @param array $options ignored
-     * @access    public
-     * @return    void
      */
     function MoodleQuickForm_modvisible($elementName=null, $elementLabel=null, $attributes=null, $options=null)
     {
@@ -26,16 +54,15 @@ class MoodleQuickForm_modvisible extends MoodleQuickForm_select{
         $this->_type = 'modvisible';
 
 
-    } //end constructor
+    }
 
     /**
      * Called by HTML_QuickForm whenever form event is made on this element
      *
-     * @param     string    $event  Name of event
+     * @param string $event Name of event
-     * @param     mixed     $arg    event arguments
+     * @param mixed $arg event arguments
-     * @param     object    $caller calling object
+     * @param object $caller calling object
-     * @access    public
+     * @return bool
-     * @return    mixed
      */
     function onQuickFormEvent($event, $arg, &$caller)
     {

lib/form/password.php

@@ -1,19 +1,54 @@
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+
+/**
+ * Password type form element
+ *
+ * Contains HTML class for a password type element
+ *
+ * @package   core_form
+ * @copyright 2006 Jamie Pratt <me@jamiep.org>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 require_once('HTML/QuickForm/password.php');
 
 /**
+ * Password type form element
+ *
  * HTML class for a password type element
  *
- * @author       Jamie Pratt
+ * @package   core_form
- * @access       public
+ * @category  form
+ * @copyright 2006 Jamie Pratt <me@jamiep.org>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class MoodleQuickForm_password extends HTML_QuickForm_password{
-    /**
+    /** @var string, html for help button, if empty then no help */
-     * html for help button, if empty then no help
-     *
-     * @var string
-     */
     var $_helpbutton='';
+
+    /**
+     * constructor
+     *
+     * @param string $elementName (optional) name of the password element
+     * @param string $elementLabel (optional) label for password element
+     * @param mixed $attributes (optional) Either a typical HTML attribute string
+     *              or an associative array
+     */
     function MoodleQuickForm_password($elementName=null, $elementLabel=null, $attributes=null) {
         global $CFG;
         if (empty($CFG->xmlstrictheaders)) {
@@ -32,21 +67,24 @@ class MoodleQuickForm_password extends HTML_QuickForm_password{
 
         parent::HTML_QuickForm_password($elementName, $elementLabel, $attributes);
     }
+
     /**
      * set html for help button
      *
-     * @access   public
+     * @param array $helpbuttonargs array of arguments to make a help button
-     * @param array $help array of arguments to make a help button
      * @param string $function function name to call to get html
+     * @deprecated since Moodle 2.0. Please do not call this function any more.
+     * @todo MDL-31047 this api will be removed.
+     * @see MoodleQuickForm::setHelpButton()
      */
     function setHelpButton($helpbuttonargs, $function='helpbutton'){
         debugging('component setHelpButton() is not used any more, please use $mform->setHelpButton() instead');
     }
+
     /**
      * get html for help button
      *
-     * @access   public
+     * @return string html for help button
-     * @return  string html for help button
      */
     function getHelpButton(){
         return $this->_helpbutton;

lib/form/passwordunmask.php

@@ -1,4 +1,30 @@
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+
+/**
+ * Password type form element with unmask option
+ *
+ * Contains HTML class for a password type element with unmask option
+ *
+ * @package   core_form
+ * @copyright 2009 Petr Skoda
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 if (!defined('MOODLE_INTERNAL')) {
     die('Direct access to this script is forbidden.');    ///  It must be included from a Moodle page
 }
@@ -7,13 +33,24 @@ global $CFG;
 require_once($CFG->libdir.'/form/password.php');
 
 /**
+ * Password type form element with unmask option
+ *
  * HTML class for a password type element with unmask option
  *
- * @author       Petr Skoda
+ * @package   core_form
- * @access       public
+ * @category  form
+ * @copyright 2009 Petr Skoda {@link http://skodak.org}
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class MoodleQuickForm_passwordunmask extends MoodleQuickForm_password {
-
+    /**
+     * constructor
+     *
+     * @param string $elementName (optional) name of the password element
+     * @param string $elementLabel (optional) label for password element
+     * @param mixed $attributes (optional) Either a typical HTML attribute string
+     *              or an associative array
+     */
     function MoodleQuickForm_passwordunmask($elementName=null, $elementLabel=null, $attributes=null) {
         global $CFG;
         if (empty($CFG->xmlstrictheaders)) {
@@ -32,6 +69,11 @@ class MoodleQuickForm_passwordunmask extends MoodleQuickForm_password {
         parent::MoodleQuickForm_password($elementName, $elementLabel, $attributes);
     }
 
+    /**
+     * Returns HTML for password form element.
+     *
+     * @return string
+     */
     function toHtml() {
         global $PAGE;
 
@@ -44,6 +86,6 @@ class MoodleQuickForm_passwordunmask extends MoodleQuickForm_password {
                     array(array('formid' => $this->getAttribute('id'), 'checkboxname' => $unmask)));
             return $this->_getTabs() . '<input' . $this->_getAttrString($this->_attributes) . ' />';
         }
-    } //end func toHtml
+    }
 
 }

lib/form/questioncategory.php

@@ -1,11 +1,28 @@
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+
 /**
- * A moodle form field type for question categories.
+ * Drop down for question categories.
  *
- * @copyright Jamie Pratt
+ * Contains HTML class for a drop down element to select a question category.
- * @author Jamie Pratt
+ *
- * @license http://www.gnu.org/copyleft/gpl.html GNU Public License
+ * @package   core_form
- * @package moodleforms
+ * @copyright 2007 Tim Hunt
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 global $CFG;
@@ -13,10 +30,17 @@ require_once("$CFG->libdir/form/selectgroups.php");
 require_once("$CFG->libdir/questionlib.php");
 
 /**
+ * Drop down for question categories.
+ *
  * HTML class for a drop down element to select a question category.
- * @access public
+ *
+ * @package   core_form
+ * @category  form
+ * @copyright 2007 Tim Hunt
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class MoodleQuickForm_questioncategory extends MoodleQuickForm_selectgroups {
+    /** @var array default options for question categories */
     var $_options = array('top'=>false, 'currentcat'=>0, 'nochildrenof' => -1);
 
     /**
@@ -24,11 +48,10 @@ class MoodleQuickForm_questioncategory extends MoodleQuickForm_selectgroups {
      *
      * @param string $elementName Select name attribute
      * @param mixed $elementLabel Label(s) for the select
-     * @param mixed $attributes Either a typical HTML attribute string or an associative array
      * @param array $options additional options. Recognised options are courseid, published and
-     * only_editable, corresponding to the arguments of question_category_options from moodlelib.php.
+     *              only_editable, corresponding to the arguments of question_category_options
-     * @access public
+     *              from moodlelib.php.
-     * @return void
+     * @param mixed $attributes Either a typical HTML attribute string or an associative array
      */
     function MoodleQuickForm_questioncategory($elementName = null, $elementLabel = null, $options = null, $attributes = null) {
         MoodleQuickForm_selectgroups::MoodleQuickForm_selectgroups($elementName, $elementLabel, array(), $attributes);

lib/form/radio.php

@@ -1,37 +1,77 @@
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+
+/**
+ * radio type form element
+ *
+ * Contains HTML class for a radio type element
+ *
+ * @package   core_form
+ * @copyright 2006 Jamie Pratt <me@jamiep.org>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 require_once('HTML/QuickForm/radio.php');
 
 /**
+ * radio type form element
+ *
  * HTML class for a radio type element
  *
- * @author       Jamie Pratt
+ * @package   core_form
- * @access       public
+ * @category  form
+ * @copyright 2006 Jamie Pratt <me@jamiep.org>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class MoodleQuickForm_radio extends HTML_QuickForm_radio{
-    /**
+    /** @var string html for help button, if empty then no help */
-     * html for help button, if empty then no help
-     *
-     * @var string
-     */
     var $_helpbutton='';
+
+    /**
+     * constructor
+     *
+     * @param string $elementName (optional) name of the radio element
+     * @param string $elementLabel (optional) label for radio element
+     * @param string $text (optional) Text to put after the radio element
+     * @param string $value (optional) default value
+     * @param mixed $attributes (optional) Either a typical HTML attribute string
+     *              or an associative array
+     */
     function MoodleQuickForm_radio($elementName=null, $elementLabel=null, $text=null, $value=null, $attributes=null) {
         parent::HTML_QuickForm_radio($elementName, $elementLabel, $text, $value, $attributes);
     }
+
     /**
      * set html for help button
      *
-     * @access   public
+     * @param array $helpbuttonargs array of arguments to make a help button
-     * @param array $help array of arguments to make a help button
      * @param string $function function name to call to get html
+     * @deprecated since Moodle 2.0. Please do not call this function any more.
+     * @todo MDL-31047 this api will be removed.
+     * @see MoodleQuickForm::setHelpButton()
      */
     function setHelpButton($helpbuttonargs, $function='helpbutton'){
         debugging('component setHelpButton() is not used any more, please use $mform->setHelpButton() instead');
     }
+
     /**
      * get html for help button
      *
-     * @access   public
+     * @return string html for help button
-     * @return  string html for help button
      */
     function getHelpButton(){
         return $this->_helpbutton;
@@ -49,9 +89,11 @@ class MoodleQuickForm_radio extends HTML_QuickForm_radio{
             return 'default';
         }
     }
+
     /**
      * Returns the disabled field. Accessibility: the return "( )" from parent
      * class is not acceptable for screenreader users, and we DO want a label.
+     *
      * @return string
      */
     function getFrozenHtml()
@@ -64,6 +106,12 @@ class MoodleQuickForm_radio extends HTML_QuickForm_radio{
         }
         return $output;
     }
+
+    /**
+     * Returns HTML for advchecbox form element.
+     *
+     * @return string
+     */
     function toHtml()
     {
         return '<span>' . parent::toHtml() . '</span>';

lib/form/recaptcha.php

@@ -1,37 +1,57 @@
 <?php
-require_once('HTML/QuickForm/input.php');
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
-/* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */
 
 /**
- * textarea_counter.php
+ * recaptcha type form element
  *
- * @category  Admin
+ * Contains HTML class for a recaptcha type element
- * @package   admin
+ *
- * @author    Nicolas Connault <nicolasconnault@gmail.com>
+ * @package   core_form
+ * @copyright 2008 Nicolas Connault <nicolasconnault@gmail.com>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
+require_once('HTML/QuickForm/input.php');
 
 /**
- * @category Admin
+ * recaptcha type form element
- * @package  admin
+ *
+ * HTML class for a recaptcha type element
+ *
+ * @package   core_form
+ * @category  form
+ * @copyright 2008 Nicolas Connault <nicolasconnault@gmail.com>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class MoodleQuickForm_recaptcha extends HTML_QuickForm_input {
 
-    /**
+    /** @var string html for help button, if empty then no help */
-     * html for help button, if empty then no help
-     *
-     * @var string
-     */
     var $_helpbutton='';
 
+    /** @var bool if true, recaptcha will be servered from https */
     var $_https=false;
 
     /**
-     * <code>
+     * constructor
-     * $form->addElement('textarea_counter', 'message', 'Message',
+     *
-     *   array('cols'=>60, 'rows'=>10), 160);
+     * @param string $elementName (optional) name of the recaptcha element
-     * </code>
+     * @param string $elementLabel (optional) label for recaptcha element
+     * @param mixed $attributes (optional) Either a typical HTML attribute string
+     *              or an associative array
      */
     function MoodleQuickForm_recaptcha($elementName = null, $elementLabel = null, $attributes = null) {
         global $CFG;
@@ -47,9 +67,7 @@ class MoodleQuickForm_recaptcha extends HTML_QuickForm_input {
     /**
      * Returns the recaptcha element in HTML
      *
-     * @since     1.0
+     * @return string
-     * @access    public
-     * @return    string
      */
     function toHtml() {
         global $CFG, $PAGE;
@@ -95,9 +113,11 @@ class MoodleQuickForm_recaptcha extends HTML_QuickForm_input {
     /**
      * set html for help button
      *
-     * @access   public
+     * @param array $helpbuttonargs array of arguments to make a help button
-     * @param array $help array of arguments to make a help button
      * @param string $function function name to call to get html
+     * @deprecated since Moodle 2.0. Please do not call this function any more.
+     * @todo MDL-31047 this api will be removed.
+     * @see MoodleQuickForm::setHelpButton()
      */
     function setHelpButton($helpbuttonargs, $function='helpbutton'){
         debugging('component setHelpButton() is not used any more, please use $mform->setHelpButton() instead');
@@ -106,13 +126,19 @@ class MoodleQuickForm_recaptcha extends HTML_QuickForm_input {
     /**
      * get html for help button
      *
-     * @access   public
+     * @return string html for help button
-     * @return  string html for help button
      */
     function getHelpButton(){
         return $this->_helpbutton;
     }
 
+    /**
+     * Checks input and challenged field
+     *
+     * @param string $challenge_field recaptcha shown  to user
+     * @param string $response_field input value by user
+     * @return bool
+     */
     function verify($challenge_field, $response_field) {
         global $CFG;
         require_once $CFG->libdir . '/recaptchalib.php';

lib/form/searchableselector.php

@@ -1,5 +1,4 @@
 <?php
-
 // This file is part of Moodle - http://moodle.org/
 //
 // Moodle is free software: you can redistribute it and/or modify
@@ -16,25 +15,40 @@
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
 /**
- * HTML class for a searchable select type element
+ * searchable select type element
  *
- * @package   formlib
+ * Contains HTML class for a searchable select type element
- * @copyright 2009 Jerome Mouneyrac
+ *
+ * @package   core_form
+ * @copyright 2009 Jerome Mouneyrac <jerome@mouneyrac.com>
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 require_once('select.php');
 
 /**
+ * searchable select type element
+ * 
  * Display a select input with a search textfield input on the top
  * The search textfield is created by the javascript file searchselector.js
  * (so when javascript is not activated into the browser, the search field is not displayed)
  * If ever the select can be reset/unselect/blank/nooption, you will have to add an option "noselected"
  * and manage this special case when you get/set the form data (i.e. $mform->get_data()/$this->set_data($yourobject)).
+ *
+ * @package   core_form
+ * @category  form
+ * @copyright 2009 Jerome Mouneyrac
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class MoodleQuickForm_searchableselector extends MoodleQuickForm_select{
-
+    /**
-
+     * Constructor
+     *
+     * @param string $elementName Select name attribute
+     * @param mixed $elementLabel Label(s) for the select
+     * @param array $options additional options. 
+     * @param mixed $attributes Either a typical HTML attribute string or an associative array
+     */
     function MoodleQuickForm_searchableselector($elementName=null, $elementLabel=null, $options=null, $attributes=null) {
         //set size default to 12
         if (empty($attributes) || empty($attributes['size'])) {
@@ -43,6 +57,11 @@ class MoodleQuickForm_searchableselector extends MoodleQuickForm_select{
         parent::MoodleQuickForm_select($elementName, $elementLabel, $options, $attributes);
     }
 
+    /**
+     * Returns the select element in HTML
+     *
+     * @return string
+     */
     function toHtml(){
         global $OUTPUT;
         if ($this->_hiddenLabel){

lib/form/select.php

@@ -1,27 +1,75 @@
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+
+/**
+ * select type form element
+ *
+ * Contains HTML class for a select type element
+ *
+ * @package   core_form
+ * @copyright 2006 Jamie Pratt <me@jamiep.org>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 require_once('HTML/QuickForm/select.php');
 
 /**
+ * select type form element
+ *
  * HTML class for a select type element
  *
- * @author       Jamie Pratt
+ * @package   core_form
- * @access       public
+ * @category  form
+ * @copyright 2006 Jamie Pratt <me@jamiep.org>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class MoodleQuickForm_select extends HTML_QuickForm_select{
-    /**
+    /** @var string html for help button, if empty then no help */
-     * html for help button, if empty then no help
-     *
-     * @var string
-     */
     var $_helpbutton='';
+
+    /** @var bool if true label will be hidden */
     var $_hiddenLabel=false;
 
+    /**
+     * constructor
+     *
+     * @param string $elementName Select name attribute
+     * @param mixed $elementLabel Label(s) for the select
+     * @param mixed $options Data to be used to populate options
+     * @param mixed $attributes Either a typical HTML attribute string or an associative array
+     */
     function MoodleQuickForm_select($elementName=null, $elementLabel=null, $options=null, $attributes=null) {
         parent::HTML_QuickForm_select($elementName, $elementLabel, $options, $attributes);
     }
+
+    /**
+     * Sets label to be hidden
+     *
+     * @param bool $hiddenLabel sets if label should be hidden
+     */
     function setHiddenLabel($hiddenLabel){
         $this->_hiddenLabel = $hiddenLabel;
     }
+
+    /**
+     * Returns HTML for select form element.
+     *
+     * @return string
+     */
     function toHtml(){
         if ($this->_hiddenLabel){
             $this->_generateId();
@@ -35,29 +83,30 @@ class MoodleQuickForm_select extends HTML_QuickForm_select{
     /**
      * set html for help button
      *
-     * @access   public
+     * @param array $helpbuttonargs array of arguments to make a help button
-     * @param array $help array of arguments to make a help button
      * @param string $function function name to call to get html
+     * @deprecated since Moodle 2.0. Please do not call this function any more.
+     * @todo MDL-31047 this api will be removed.
+     * @see MoodleQuickForm::setHelpButton()
      */
     function setHelpButton($helpbuttonargs, $function='helpbutton'){
         debugging('component setHelpButton() is not used any more, please use $mform->setHelpButton() instead');
     }
+
     /**
      * get html for help button
      *
-     * @access   public
+     * @return string html for help button
-     * @return  string html for help button
      */
     function getHelpButton(){
         return $this->_helpbutton;
     }
+
     /**
      * Removes an OPTION from the SELECT
      *
-     * @param     string    $value      Value for the OPTION to remove
+     * @param string $value Value for the OPTION to remove
-     * @since     1.0
+     * @return void
-     * @access    public
-     * @return    void
      */
     function removeOption($value)
     {
@@ -73,19 +122,16 @@ class MoodleQuickForm_select extends HTML_QuickForm_select{
                 return;
             }
         }
-    } // end func removeOption
+    }
+
     /**
      * Removes all OPTIONs from the SELECT
-     *
-     * @param     string    $value      Value for the OPTION to remove
-     * @since     1.0
-     * @access    public
-     * @return    void
      */
     function removeOptions()
     {
         $this->_options = array();
-    } // end func removeOption
+    }
+
     /**
      * Slightly different container template when frozen. Don't want to use a label tag
      * with a for attribute in that case for the element label but instead use a div.
@@ -100,9 +146,14 @@ class MoodleQuickForm_select extends HTML_QuickForm_select{
             return 'default';
         }
     }
+
    /**
     * We check the options and return only the values that _could_ have been
     * selected. We also return a scalar value if select is not "multiple"
+    *
+    * @param array $submitValues submitted values
+    * @param bool $assoc if true the retured value is associated array
+    * @return mixed
     */
     function exportValue(&$submitValues, $assoc = false)
     {

lib/form/selectgroups.php

@@ -1,79 +1,67 @@
 <?php
-/* vim: set expandtab tabstop=4 shiftwidth=4: */
+// This file is part of Moodle - http://moodle.org/
-// +----------------------------------------------------------------------+
+//
-// | PHP version 4.0                                                      |
+// Moodle is free software: you can redistribute it and/or modify
-// +----------------------------------------------------------------------+
+// it under the terms of the GNU General Public License as published by
-// | Copyright (c) 1997-2003 The PHP Group                                |
+// the Free Software Foundation, either version 3 of the License, or
-// +----------------------------------------------------------------------+
+// (at your option) any later version.
-// | This source file is subject to version 2.0 of the PHP license,       |
+//
-// | that is bundled with this package in the file LICENSE, and is        |
+// Moodle is distributed in the hope that it will be useful,
-// | available at through the world-wide-web at                           |
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
-// | http://www.php.net/license/2_02.txt.                                 |
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-// | If you did not receive a copy of the PHP license and are unable to   |
+// GNU General Public License for more details.
-// | obtain it through the world-wide-web, please send a note to          |
+//
-// | license@php.net so we can mail you a copy immediately.               |
+// You should have received a copy of the GNU General Public License
-// +----------------------------------------------------------------------+
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
-// | Authors: Adam Daniel <adaniel1@eesus.jnj.com>                        |
+
-// |          Bertrand Mansion <bmansion@mamasam.com>                     |
+
-// +----------------------------------------------------------------------+
+/**
+ * select type form element
+ *
+ * Class to dynamically create an HTML SELECT with all options grouped in optgroups
+ *
+ * @package   core_form
+ * @copyright 2007 Jamie Pratt <me@jamiep.org>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 
 require_once('HTML/QuickForm/element.php');
 
 /**
+ * select type form element
+ *
  * Class to dynamically create an HTML SELECT with all options grouped in optgroups
  *
- * @author       Adam Daniel <adaniel1@eesus.jnj.com>
+ * @package   core_form
- * @author       Bertrand Mansion <bmansion@mamasam.com>
+ * @category  form
- * @version      1.0
+ * @copyright 2007 Jamie Pratt <me@jamiep.org>
- * @since        PHP4.04pl1
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @access       public
  */
 class MoodleQuickForm_selectgroups extends HTML_QuickForm_element {
 
-    // {{{ properties
+    /** @var bool add choose option */
-
-    /** add choose option */
     var $showchoose = false;
 
-    /**
+    /** @var array Contains the select optgroups */
-     * Contains the select optgroups
-     *
-     * @var       array
-     * @since     1.0
-     * @access    private
-     */
     var $_optGroups = array();
 
-    /**
+    /** @var string Default values of the SELECT */
-     * Default values of the SELECT
-     *
-     * @var       string
-     * @since     1.0
-     * @access    private
-     */
     var $_values = null;
 
-    /**
+    /** @var string html for help button, if empty then no help */
-     * html for help button, if empty then no help
-     *
-     * @var string
-     */
     var $_helpbutton='';
+
+    /** @var bool if true label will be hidden */
     var $_hiddenLabel=false;
 
     /**
      * Class constructor
      *
-     * @param     string    Select name attribute
+     * @param string $elementName Select name attribute
-     * @param     mixed     Label(s) for the select
+     * @param mixed $elementLabel Label(s) for the select
-     * @param     mixed     Data to be used to populate options
+     * @param array $optgrps Data to be used to populate options
-     * @param     mixed     An array whose keys are labels for optgroups and whose values are arrays similar to those passed
+     * @param mixed $attributes Either a typical HTML attribute string or an associative array
-     *                          to the select element with keys that are values for options and values are strings for display.
+     * @param bool $showchoose add standard moodle "Choose..." option as first item
-     * @param     mixed     Either a typical HTML attribute string or an associative array
-     * @param     bool      add standard moodle "Choose..." option as first item
-     * @since     1.0
-     * @access    public
-     * @return    void
      */
     function MoodleQuickForm_selectgroups($elementName=null, $elementLabel=null, $optgrps=null, $attributes=null, $showchoose=false)
     {
@@ -84,19 +72,12 @@ class MoodleQuickForm_selectgroups extends HTML_QuickForm_element {
         if (isset($optgrps)) {
             $this->loadArrayOptGroups($optgrps);
         }
-    } //end constructor
+    }
-
-    // }}}
-    // {{{ apiVersion()
-
 
     /**
      * Sets the default values of the select box
      *
-     * @param     mixed    $values  Array or comma delimited string of selected values
+     * @param mixed $values Array or comma delimited string of selected values
-     * @since     1.0
-     * @access    public
-     * @return    void
      */
     function setSelected($values)
     {
@@ -108,63 +89,42 @@ class MoodleQuickForm_selectgroups extends HTML_QuickForm_element {
         } else {
             $this->_values = array($values);
         }
-    } //end func setSelected
+    }
-
-    // }}}
-    // {{{ getSelected()
 
     /**
      * Returns an array of the selected values
      *
-     * @since     1.0
+     * @return array of selected values
-     * @access    public
-     * @return    array of selected values
      */
     function getSelected()
     {
         return $this->_values;
-    } // end func getSelected
+    }
-
-    // }}}
-    // {{{ setName()
 
     /**
      * Sets the input field name
      *
-     * @param     string    $name   Input field name attribute
+     * @param string $name Input field name attribute
-     * @since     1.0
-     * @access    public
-     * @return    void
      */
     function setName($name)
     {
         $this->updateAttributes(array('name' => $name));
-    } //end func setName
+    }
-
-    // }}}
-    // {{{ getName()
 
     /**
      * Returns the element name
      *
-     * @since     1.0
+     * @return string
-     * @access    public
-     * @return    string
      */
     function getName()
     {
         return $this->getAttribute('name');
-    } //end func getName
+    }
-
-    // }}}
-    // {{{ getPrivateName()
 
     /**
      * Returns the element name (possibly with brackets appended)
      *
-     * @since     1.0
+     * @return string
-     * @access    public
-     * @return    string
      */
     function getPrivateName()
     {
@@ -173,80 +133,52 @@ class MoodleQuickForm_selectgroups extends HTML_QuickForm_element {
         } else {
             return $this->getName();
         }
-    } //end func getPrivateName
+    }
-
-    // }}}
-    // {{{ setValue()
 
     /**
      * Sets the value of the form element
      *
-     * @param     mixed    $values  Array or comma delimited string of selected values
+     * @param mixed $value Array or comma delimited string of selected values
-     * @since     1.0
-     * @access    public
-     * @return    void
      */
     function setValue($value)
     {
         $this->setSelected($value);
-    } // end func setValue
+    }
-
-    // }}}
-    // {{{ getValue()
 
     /**
      * Returns an array of the selected values
      *
-     * @since     1.0
+     * @return array of selected values
-     * @access    public
-     * @return    array of selected values
      */
     function getValue()
     {
         return $this->_values;
-    } // end func getValue
+    }
-
-    // }}}
-    // {{{ setSize()
 
     /**
      * Sets the select field size, only applies to 'multiple' selects
      *
-     * @param     int    $size  Size of select  field
+     * @param int $size Size of select  field
-     * @since     1.0
-     * @access    public
-     * @return    void
      */
     function setSize($size)
     {
         $this->updateAttributes(array('size' => $size));
-    } //end func setSize
+    }
-
-    // }}}
-    // {{{ getSize()
 
     /**
      * Returns the select field size
      *
-     * @since     1.0
+     * @return int
-     * @access    public
-     * @return    int
      */
     function getSize()
     {
         return $this->getAttribute('size');
-    } //end func getSize
+    }
-
-    // }}}
-    // {{{ setMultiple()
 
     /**
      * Sets the select mutiple attribute
      *
-     * @param     bool    $multiple  Whether the select supports multi-selections
+     * @param bool $multiple Whether the select supports multi-selections
-     * @since     1.2
-     * @access    public
-     * @return    void
      */
     function setMultiple($multiple)
     {
@@ -255,32 +187,25 @@ class MoodleQuickForm_selectgroups extends HTML_QuickForm_element {
         } else {
             $this->removeAttribute('multiple');
         }
-    } //end func setMultiple
+    }
-
-    // }}}
-    // {{{ getMultiple()
 
     /**
      * Returns the select mutiple attribute
      *
-     * @since     1.2
+     * @return bool true if multiple select, false otherwise
-     * @access    public
-     * @return    bool    true if multiple select, false otherwise
      */
     function getMultiple()
     {
         return (bool)$this->getAttribute('multiple');
-    } //end func getMultiple
+    }
 
     /**
      * Loads the options from an associative array
      *
-     * @param     array    $arr     Associative array of options
+     * @param array $arr Associative array of options
-     * @param     mixed    $values  (optional) Array or comma delimited string of selected values
+     * @param mixed $values (optional) Array or comma delimited string of selected values
-     * @since     1.0
+     * @return PEAR_Error|bool on error or true
-     * @access    public
+     * @throws PEAR_Error
-     * @return    PEAR_Error on error or true
-     * @throws    PEAR_Error
      */
     function loadArrayOptGroups($arr, $values=null)
     {
@@ -296,16 +221,14 @@ class MoodleQuickForm_selectgroups extends HTML_QuickForm_element {
         }
         return true;
     }
+
     /**
      * Adds a new OPTION to the SELECT
      *
-     * @param     string    $text       Display text for the OPTION
+     * @param string $text Display text for the OPTION
-     * @param     string    $value      Value for the OPTION
+     * @param string $value Value for the OPTION
-     * @param     mixed     $attributes Either a typical HTML attribute string
+     * @param mixed $attributes Either a typical HTML attribute string
-     *                                  or an associative array
+     *              or an associative array
-     * @since     1.0
-     * @access    public
-     * @return    void
      */
     function addOptGroup($text, $value, $attributes=null)
     {
@@ -323,12 +246,11 @@ class MoodleQuickForm_selectgroups extends HTML_QuickForm_element {
     /**
      * Loads the options from an associative array
      *
-     * @param     array    $arr     Associative array of options
+     * @param string $optgroup name of the options group
-     * @param     mixed    $values  (optional) Array or comma delimited string of selected values
+     * @param array $arr Associative array of options
-     * @since     1.0
+     * @param mixed $values (optional) Array or comma delimited string of selected values
-     * @access    public
+     * @return PEAR_Error|bool on error or true
-     * @return    PEAR_Error on error or true
+     * @throws PEAR_Error
-     * @throws    PEAR_Error
      */
     function loadArrayOptions($optgroup, $arr, $values=null)
     {
@@ -348,13 +270,11 @@ class MoodleQuickForm_selectgroups extends HTML_QuickForm_element {
     /**
      * Adds a new OPTION to an optgroup
      *
-     * @param     string    $text       Display text for the OPTION
+     * @param string $optgroup name of the option group
-     * @param     string    $value      Value for the OPTION
+     * @param string $text Display text for the OPTION
-     * @param     mixed     $attributes Either a typical HTML attribute string
+     * @param string $value Value for the OPTION
-     *                                  or an associative array
+     * @param mixed $attributes Either a typical HTML attribute string
-     * @since     1.0
+     *              or an associative array
-     * @access    public
-     * @return    void
      */
     function addOption($optgroup, $text, $value, $attributes=null)
     {
@@ -379,9 +299,7 @@ class MoodleQuickForm_selectgroups extends HTML_QuickForm_element {
     /**
      * Returns the SELECT in HTML
      *
-     * @since     1.0
+     * @return string
-     * @access    public
-     * @return    string
      */
     function toHtml()
     {
@@ -430,17 +348,12 @@ class MoodleQuickForm_selectgroups extends HTML_QuickForm_element {
             }
             return $strHtml . $tabs . '</select>';
         }
-    } //end func toHtml
+    }
-
-    // }}}
-    // {{{ getFrozenHtml()
 
     /**
      * Returns the value of field without HTML tags
      *
-     * @since     1.0
+     * @return string
-     * @access    public
-     * @return    string
      */
     function getFrozenHtml()
     {
@@ -476,14 +389,15 @@ class MoodleQuickForm_selectgroups extends HTML_QuickForm_element {
             }
         }
         return $html;
-    } //end func getFrozenHtml
+    }
-
-    // }}}
-    // {{{ exportValue()
 
    /**
     * We check the options and return only the values that _could_ have been
     * selected. We also return a scalar value if select is not "multiple"
+    *
+    * @param array $submitValues submitted values
+    * @param bool $assoc if true the retured value is associated array
+    * @return mixed
     */
     function exportValue(&$submitValues, $assoc = false)
     {
@@ -522,9 +436,14 @@ class MoodleQuickForm_selectgroups extends HTML_QuickForm_element {
         }
     }
     
-    // }}}
+    /**
-    // {{{ onQuickFormEvent()
+     * Called by HTML_QuickForm whenever form event is made on this element
-
+     *
+     * @param string $event Name of event
+     * @param mixed $arg event arguments
+     * @param object $caller calling object
+     * @return bool
+     */
     function onQuickFormEvent($event, $arg, &$caller)
     {
         if ('updateValue' == $event) {
@@ -545,24 +464,33 @@ class MoodleQuickForm_selectgroups extends HTML_QuickForm_element {
             return parent::onQuickFormEvent($event, $arg, $caller);
         }
     }
+
+    /**
+     * Sets label to be hidden
+     *
+     * @param bool $hiddenLabel sets if label should be hidden
+     */
     function setHiddenLabel($hiddenLabel){
         $this->_hiddenLabel = $hiddenLabel;
     }
+
     /**
      * set html for help button
      *
-     * @access   public
+     * @param array $helpbuttonargs array of arguments to make a help button
-     * @param array $help array of arguments to make a help button
      * @param string $function function name to call to get html
+     * @deprecated since Moodle 2.0. Please do not call this function any more.
+     * @todo MDL-31047 this api will be removed.
+     * @see MoodleQuickForm::setHelpButton()
      */
     function setHelpButton($helpbuttonargs, $function='helpbutton'){
         debugging('component setHelpButton() is not used any more, please use $mform->setHelpButton() instead');
     }
+
     /**
      * get html for help button
      *
-     * @access   public
+     * @return string html for help button
-     * @return  string html for help button
      */
     function getHelpButton(){
         return $this->_helpbutton;

lib/form/selectwithlink.php

@@ -1,24 +1,67 @@
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+
+/**
+ * select type form element
+ *
+ * Contains HTML class for a select type element with options containing link
+ *
+ * @package   core_form
+ * @copyright 2008 Nicolas Connault <nicolasconnault@gmail.com>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 require_once('HTML/QuickForm/select.php');
 
 /**
- * HTML class for a select type element
+ * select type form element
  *
- * @author       Jamie Pratt
+ * HTML class for a select type element with options containing link
- * @access       public
+ *
+ * @package   core_form
+ * @category  form
+ * @copyright 2008 Nicolas Connault <nicolasconnault@gmail.com>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class MoodleQuickForm_selectwithlink extends HTML_QuickForm_select{
-    /**
+    /** @var string html for help button, if empty then no help */
-     * html for help button, if empty then no help
-     *
-     * @var string
-     */
     var $_helpbutton='';
+
+    /** @var bool if true label will be hidden */
     var $_hiddenLabel=false;
+
+    /** @var string url to which select option will be posted */
     var $_link=null;
+
+    /** @var string data which will be posted to link */
     var $_linklabel=null;
+
+    /** @var string url return link */
     var $_linkreturn=null;
 
+    /**
+     * constructor
+     *
+     * @param string $elementName Select name attribute
+     * @param mixed $elementLabel Label(s) for the select
+     * @param array $options Data to be used to populate options
+     * @param mixed $attributes Either a typical HTML attribute string or an associative array
+     * @param bool $linkdata data to be posted
+     */
     function MoodleQuickForm_selectwithlink($elementName=null, $elementLabel=null, $options=null, $attributes=null, $linkdata=null)
     {
         if (!empty($linkdata['link']) && !empty($linkdata['label'])) {
@@ -31,11 +74,22 @@ class MoodleQuickForm_selectwithlink extends HTML_QuickForm_select{
         }
 
         parent::HTML_QuickForm_select($elementName, $elementLabel, $options, $attributes);
-    } //end constructor
+    }
 
+    /**
+     * Sets label to be hidden
+     *
+     * @param bool $hiddenLabel sets if label should be hidden
+     */
     function setHiddenLabel($hiddenLabel){
         $this->_hiddenLabel = $hiddenLabel;
     }
+
+    /**
+     * Returns the SELECT in HTML
+     *
+     * @return string
+     */
     function toHtml(){
         $retval = '';
         if ($this->_hiddenLabel){
@@ -68,29 +122,29 @@ class MoodleQuickForm_selectwithlink extends HTML_QuickForm_select{
     /**
      * set html for help button
      *
-     * @access   public
+     * @param array $helpbuttonargs array of arguments to make a help button
-     * @param array $help array of arguments to make a help button
      * @param string $function function name to call to get html
+     * @deprecated since Moodle 2.0. Please do not call this function any more.
+     * @todo MDL-31047 this api will be removed.
+     * @see MoodleQuickForm::setHelpButton()
      */
     function setHelpButton($helpbuttonargs, $function='helpbutton'){
         debugging('component setHelpButton() is not used any more, please use $mform->setHelpButton() instead');
     }
+
     /**
      * get html for help button
      *
-     * @access   public
+     * @return string html for help button
-     * @return  string html for help button
      */
     function getHelpButton(){
         return $this->_helpbutton;
     }
+
     /**
      * Removes an OPTION from the SELECT
      *
-     * @param     string    $value      Value for the OPTION to remove
+     * @param string $value Value for the OPTION to remove
-     * @since     1.0
-     * @access    public
-     * @return    void
      */
     function removeOption($value)
     {
@@ -104,19 +158,16 @@ class MoodleQuickForm_selectwithlink extends HTML_QuickForm_select{
                 return;
             }
         }
-    } // end func removeOption
+    }
+
     /**
      * Removes all OPTIONs from the SELECT
-     *
-     * @param     string    $value      Value for the OPTION to remove
-     * @since     1.0
-     * @access    public
-     * @return    void
      */
     function removeOptions()
     {
         $this->_options = array();
-    } // end func removeOption
+    }
+
     /**
      * Slightly different container template when frozen. Don't want to use a label tag
      * with a for attribute in that case for the element label but instead use a div.
@@ -131,9 +182,14 @@ class MoodleQuickForm_selectwithlink extends HTML_QuickForm_select{
             return 'default';
         }
     }
+
    /**
     * We check the options and return only the values that _could_ have been
     * selected. We also return a scalar value if select is not "multiple"
+    *
+    * @param array $submitValues submitted values
+    * @param bool $assoc if true the retured value is associated array
+    * @return mixed
     */
     function exportValue(&$submitValues, $assoc = false)
     {

lib/form/selectyesno.php

@@ -1,42 +1,66 @@
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+
+/**
+ * Yes/No drop down type form element
+ *
+ * Contains HTML class for a simple yes/ no drop down element
+ *
+ * @package   core_form
+ * @copyright 2006 Jamie Pratt <me@jamiep.org>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 global $CFG;
 require_once "$CFG->libdir/form/select.php";
 
 /**
+ * Yes/No drop down type form element
+ *
  * HTML class for a simple yes/ no drop down element
  *
- * @author       Jamie Pratt
+ * @package   core_form
- * @access       public
+ * @category  form
+ * @copyright 2006 Jamie Pratt <me@jamiep.org>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class MoodleQuickForm_selectyesno extends MoodleQuickForm_select{
-
-
     /**
      * Class constructor
      *
-     * @param     string    Select name attribute
+     * @param string $elementName Select name attribute
-     * @param     mixed     Label(s) for the select
+     * @param mixed $elementLabel Label(s) for the select
-     * @param     mixed     Either a typical HTML attribute string or an associative array
+     * @param mixed $attributes Either a typical HTML attribute string or an associative array
-     * @param     mixed     $options ignored
+     * @param mixed $options ignored, not used.
-     * @access    public
-     * @return    void
      */
     function MoodleQuickForm_selectyesno($elementName=null, $elementLabel=null, $attributes=null, $options=null)
     {
         HTML_QuickForm_element::HTML_QuickForm_element($elementName, $elementLabel, $attributes, null);
         $this->_type = 'selectyesno';
 
-    } //end constructor
+    }
 
     /**
      * Called by HTML_QuickForm whenever form event is made on this element
      *
-     * @param     string    $event  Name of event
+     * @param string $event Name of event
-     * @param     mixed     $arg    event arguments
+     * @param mixed $arg event arguments
-     * @param     object    $caller calling object
+     * @param object $caller calling object
-     * @since     1.0
+     * @return mixed
-     * @access    public
-     * @return    mixed
      */
     function onQuickFormEvent($event, $arg, &$caller)
     {

lib/form/simpletest/testduration.php

@@ -1,27 +1,29 @@
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
-///////////////////////////////////////////////////////////////////////////
+
-//                                                                       //
+/**
-// NOTICE OF COPYRIGHT                                                   //
+ * Unit tests for forms lib.
-//                                                                       //
+ *
-// Moodle - Modular Object-Oriented Dynamic Learning Environment         //
+ * This file contains all unit test related to forms library.
-//          http://moodle.org                                            //
+ *
-//                                                                       //
+ * @package    core_form
-// Copyright (C) 1999 onwards Martin Dougiamas  http://dougiamas.com     //
+ * @copyright  2009 Tim Hunt
-//                                                                       //
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
-// This program is free software; you can redistribute it and/or modify  //
+ */
-// it under the terms of the GNU General Public License as published by  //
-// the Free Software Foundation; either version 2 of the License, or     //
-// (at your option) any later version.                                   //
-//                                                                       //
-// This program is distributed in the hope that it will be useful,       //
-// but WITHOUT ANY WARRANTY; without even the implied warranty of        //
-// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         //
-// GNU General Public License for more details:                          //
-//                                                                       //
-//          http://www.gnu.org/copyleft/gpl.html                         //
-//                                                                       //
-///////////////////////////////////////////////////////////////////////////
 
 if (!defined('MOODLE_INTERNAL')) {
     die('Direct access to this script is forbidden.');    ///  It must be included from a Moodle page
@@ -31,29 +33,49 @@ global $CFG;
 require_once($CFG->libdir . '/form/duration.php');
 
 /**
- * Unit tests for (some of) ../duration.php.
+ * Unit tests for MoodleQuickForm_duration
  *
- * @license http://www.gnu.org/copyleft/gpl.html GNU Public License
+ * Contains test cases for testing MoodleQuickForm_duration
- * @package formslib
+ * 
+ * @package    core_form
+ * @category   unittest
+ * @copyright  2009 Tim Hunt
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class duration_form_element_test extends UnitTestCase {
+    /** @var MoodleQuickForm_duration Keeps reference of MoodleQuickForm_duration object */
     private $element;
-    public  static $includecoverage = array('lib/form/duration.php');
 
+    /** @var array Path of MoodleQuickForm_duration, to be analysed by the coverage report */
+    public static $includecoverage = array('lib/form/duration.php');
+
+    /**
+     * Initalize test wide variable, it is called in start of the testcase
+     */
     function setUp() {
         $this->element = new MoodleQuickForm_duration();
     }
 
+    /**
+     * Clears the data set in the setUp() method call.
+     * @see duration_form_element_test::setUp()
+     */
     function tearDown() {
         $this->element = null;
     }
 
+    /**
+     * Testcase for testing contructor.
+     */
     function test_constructor() {
         // Test trying to create with an invalid unit.
         $this->expectException();
         $this->element = new MoodleQuickForm_duration('testel', null, array('defaultunit' => 123));
     }
 
+    /**
+     * Testcase for testing units (seconds, minutes, hours and days)
+     */
     function test_get_units() {
         $units = $this->element->get_units();
         ksort($units);
@@ -61,6 +83,9 @@ class duration_form_element_test extends UnitTestCase {
                 3600 => get_string('hours'), 86400 => get_string('days')));
     }
 
+    /**
+     * Testcase for testing conversion of seconds to the best possible unit
+     */
     function test_seconds_to_unit() {
         $this->assertEqual($this->element->seconds_to_unit(0), array(0, 60)); // Zero minutes, for a nice default unit.
         $this->assertEqual($this->element->seconds_to_unit(1), array(1, 1));
@@ -76,6 +101,9 @@ class duration_form_element_test extends UnitTestCase {
         $this->assertEqual($this->element->seconds_to_unit(0), array(0, 86400)); // Zero minutes, for a nice default unit.
     }
 
+    /**
+     * Testcase to check generated timestamp
+     */
     function test_exportValue() {
         $el = new MoodleQuickForm_duration('testel');
         $el->_createElements();

lib/form/static.php

@@ -1,43 +1,87 @@
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+
+/**
+ * Text type form element
+ *
+ * Contains HTML class for a text type element
+ *
+ * @package   core_form
+ * @copyright 2006 Jamie Pratt <me@jamiep.org>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 require_once("HTML/QuickForm/static.php");
 
 /**
+ * Text type element
+ *
  * HTML class for a text type element
  *
- * @author       Jamie Pratt
+ * @package   core_form
- * @access       public
+ * @category  form
+ * @copyright 2006 Jamie Pratt <me@jamiep.org>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class MoodleQuickForm_static extends HTML_QuickForm_static{
+    /** @var string Form element type */
     var $_elementTemplateType='static';
-    /**
+
-     * html for help button, if empty then no help
+    /** @var string html for help button, if empty then no help */
-     *
-     * @var string
-     */
     var $_helpbutton='';
+
+    /**
+     * constructor
+     *
+     * @param string $elementName (optional) name of the text field
+     * @param string $elementLabel (optional) text field label
+     * @param string $text (optional) Text to put in text field
+     */
     function MoodleQuickForm_static($elementName=null, $elementLabel=null, $text=null) {
         parent::HTML_QuickForm_static($elementName, $elementLabel, $text);
     }
+
     /**
      * set html for help button
      *
-     * @access   public
+     * @param array $helpbuttonargs array of arguments to make a help button
-     * @param array $help array of arguments to make a help button
      * @param string $function function name to call to get html
+     * @deprecated since Moodle 2.0. Please do not call this function any more.
+     * @todo MDL-31047 this api will be removed.
+     * @see MoodleQuickForm::setHelpButton()
      */
     function setHelpButton($helpbuttonargs, $function='helpbutton'){
         debugging('component setHelpButton() is not used any more, please use $mform->setHelpButton() instead');
     }
+
     /**
      * get html for help button
      *
-     * @access   public
+     * @return string html for help button
-     * @return  string html for help button
      */
     function getHelpButton(){
         return $this->_helpbutton;
     }
 
+    /**
+     * Gets the type of form element
+     *
+     * @return string
+     */
     function getElementTemplateType(){
         return $this->_elementTemplateType;
     }

lib/form/submit.php

@@ -1,28 +1,60 @@
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+
+/**
+ * submit type form element
+ *
+ * Contains HTML class for a submit type element
+ *
+ * @package   core_form
+ * @copyright 2006 Jamie Pratt <me@jamiep.org>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 require_once("HTML/QuickForm/submit.php");
 
 /**
+ * submit type form element
+ *
  * HTML class for a submit type element
  *
- * @author       Adam Daniel <adaniel1@eesus.jnj.com>
+ * @package   core_form
- * @author       Bertrand Mansion <bmansion@mamasam.com>
+ * @category  form
- * @version      1.0
+ * @copyright 2006 Jamie Pratt <me@jamiep.org>
- * @since        PHP4.04pl1
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @access       public
  */
 class MoodleQuickForm_submit extends HTML_QuickForm_submit {
+    /**
+     * constructor
+     *
+     * @param string $elementName (optional) name of the field
+     * @param string $value (optional) field label
+     * @param string $attributes (optional) Either a typical HTML attribute string or an associative array
+     */
     function MoodleQuickForm_submit($elementName=null, $value=null, $attributes=null) {
         parent::HTML_QuickForm_submit($elementName, $value, $attributes);
     }
+
     /**
      * Called by HTML_QuickForm whenever form event is made on this element
      *
-     * @param     string    $event  Name of event
+     * @param string $event Name of event
-     * @param     mixed     $arg    event arguments
+     * @param mixed $arg event arguments
-     * @param     object    $caller calling object
+     * @param object $caller calling object
-     * @since     1.0
-     * @access    public
-     * @return    void
      */
     function onQuickFormEvent($event, $arg, &$caller)
     {
@@ -43,7 +75,8 @@ class MoodleQuickForm_submit extends HTML_QuickForm_submit {
         }
         return parent::onQuickFormEvent($event, $arg, $caller);
 
-    } // end func onQuickFormEvent
+    }
+
     /**
      * Slightly different container template when frozen. Don't want to display a submit
      * button if the form is frozen.
@@ -58,6 +91,9 @@ class MoodleQuickForm_submit extends HTML_QuickForm_submit {
         }
     }
 
+    /**
+     * Freeze the element so that only its value is returned
+     */
     function freeze(){
         $this->_flagFrozen = true;
     }

lib/form/submitlink.php

@@ -1,13 +1,65 @@
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+
+/**
+ * submit link type form element
+ *
+ * Contains HTML class for a submitting to link
+ *
+ * @package   core_form
+ * @copyright 2006 Jamie Pratt <me@jamiep.org>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 global $CFG;
 require_once("$CFG->libdir/form/submit.php");
+/**
+ * submit link type form element
+ *
+ * HTML class for a submitting to link
+ *
+ * @package   core_form
+ * @category  form
+ * @copyright 2006 Jamie Pratt <me@jamiep.org>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class MoodleQuickForm_submitlink extends MoodleQuickForm_submit {
+    /** @var string javascript for submitting element's data */
     var $_js;
+
+    /** @var string callback function which will be called onclick event */
     var $_onclick;
+
+    /**
+     * constructor
+     *
+     * @param string $elementName (optional) name of the field
+     * @param string $value (optional) field label
+     * @param string $attributes (optional) Either a typical HTML attribute string or an associative array
+     */
     function MoodleQuickForm_submitlink($elementName=null, $value=null, $attributes=null) {
         parent::MoodleQuickForm_submit($elementName, $value, $attributes);
     }
 
+    /**
+     * Returns HTML for submitlink form element.
+     *
+     * @return string
+     */
     function toHtml() {
         $text = $this->_attributes['value'];
         $onmouseover = "window.status=\'" . $text . "\';";

lib/form/tags.php

@@ -1,56 +1,67 @@
 <?php
-///////////////////////////////////////////////////////////////////////////
+// This file is part of Moodle - http://moodle.org/
-//                                                                       //
+//
-// NOTICE OF COPYRIGHT                                                   //
+// Moodle is free software: you can redistribute it and/or modify
-//                                                                       //
+// it under the terms of the GNU General Public License as published by
-// Moodle - Modular Object-Oriented Dynamic Learning Environment         //
+// the Free Software Foundation, either version 3 of the License, or
-//          http://moodle.org                                            //
+// (at your option) any later version.
-//                                                                       //
+//
-// Copyright (C) 1999 onwards Martin Dougiamas  http://dougiamas.com     //
+// Moodle is distributed in the hope that it will be useful,
-//                                                                       //
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
-// This program is free software; you can redistribute it and/or modify  //
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-// it under the terms of the GNU General Public License as published by  //
+// GNU General Public License for more details.
-// the Free Software Foundation; either version 2 of the License, or     //
+//
-// (at your option)  later version.                                      //
+// You should have received a copy of the GNU General Public License
-//                                                                       //
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
-// This program is distributed in the hope that it will be useful,       //
+
-// but WITHOUT ANY WARRANTY; without even the implied warranty of        //
-// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         //
-// GNU General Public License for more details:                          //
-//                                                                       //
-//          http://www.gnu.org/copyleft/gpl.html                         //
-//                                                                       //
-///////////////////////////////////////////////////////////////////////////
 
 /**
- * Formslib field type for editing tags, both official and peronal.
+ * Drop down for question categories.
  *
- * @license http://www.gnu.org/copyleft/gpl.html GNU Public License
+ * Contains HTML class for editing tags, both official and peronal.
- * @package formslib
+ *
- *//* **/
+ * @package   core_form
+ * @copyright 2009 Tim Hunt
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 global $CFG;
 require_once($CFG->libdir . '/form/group.php');
 
 /**
- * Formslib field type for editing tags.
+ * Form field type for editing tags.
+ *
+ * HTML class for editing tags, both official and peronal.
+ *
+ * @package   core_form
+ * @category  form
+ * @copyright 2009 Tim Hunt
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class MoodleQuickForm_tags extends MoodleQuickForm_group {
-    /** Inidcates that the user should be the usual interface, with the official
+    /**
+     * Inidcates that the user should be the usual interface, with the official
      * tags listed seprately, and a text box where they can type anything.
-     * @var integer */
+     * @var int
+     */
     const DEFAULTUI = 'defaultui';
-    /** Indicates that the user should only be allowed to select official tags.
+
-     * @var integer */
+    /**
+     * Indicates that the user should only be allowed to select official tags.
+     * @var int
+     */
     const ONLYOFFICIAL = 'onlyofficial';
-    /** Indicates that the user should just be given a text box to type in (they
+
+    /**
+     * Indicates that the user should just be given a text box to type in (they
      * can still type official tags though.
-     * @var integer */
+     * @var int
+     */
     const NOOFFICIAL = 'noofficial';
 
     /**
-     * Control the fieldnames for form elements
+     * Control the fieldnames for form elements display => int, one of the constants above.
-     *
+     * @var array
-     * display => integer, one of the constants above.
      */
     protected $_options = array('display' => MoodleQuickForm_tags::DEFAULTUI);
 
@@ -91,6 +102,11 @@ class MoodleQuickForm_tags extends MoodleQuickForm_group {
         }
     }
 
+    /**
+     * Internal function to load official tags
+     *
+     * @access protected
+     */
     protected function _load_official_tags() {
         global $CFG, $DB;
         if (!is_null($this->_officialtags)) {
@@ -100,6 +116,9 @@ class MoodleQuickForm_tags extends MoodleQuickForm_group {
         $this->_officialtags = $DB->get_records_menu('tag', array('tagtype' => 'official'), $namefield, 'id,' . $namefield);
     }
 
+    /**
+     * Creates the group's elements.
+     */
     function _createElements() {
         global $CFG, $OUTPUT;
         $this->_elements = array();
@@ -159,6 +178,13 @@ class MoodleQuickForm_tags extends MoodleQuickForm_group {
         }
     }
 
+    /**
+     * Called by HTML_QuickForm whenever form event is made on this element
+     *
+     * @param string $event Name of event
+     * @param mixed $arg event arguments
+     * @param object $caller calling object
+     */
     function onQuickFormEvent($event, $arg, &$caller) {
         switch ($event) {
             case 'updateValue':
@@ -207,6 +233,11 @@ class MoodleQuickForm_tags extends MoodleQuickForm_group {
         }
     }
 
+    /**
+     * Returns HTML for submitlink form element.
+     *
+     * @return string
+     */
     function toHtml() {
         require_once('HTML/QuickForm/Renderer/Default.php');
         $renderer = new HTML_QuickForm_Renderer_Default();
@@ -215,11 +246,25 @@ class MoodleQuickForm_tags extends MoodleQuickForm_group {
         return $renderer->toHtml();
     }
 
+    /**
+     * Accepts a renderer
+     *
+     * @param HTML_QuickForm_Renderer $renderer An HTML_QuickForm_Renderer object
+     * @param bool $required Whether a group is required
+     * @param string $error An error message associated with a group
+     */
     function accept(&$renderer, $required = false, $error = null)
     {
         $renderer->renderElement($this, $required, $error);
     }
 
+    /**
+     * Output both official and peronal.
+     *
+     * @param array $submitValues values submitted.
+     * @param bool $assoc specifies if returned array is associative
+     * @return array
+     */
     function exportValue(&$submitValues, $assoc = false) {
         $valuearray = array();
 

lib/form/text.php

@@ -1,28 +1,74 @@
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+
+/**
+ * Text type form element
+ *
+ * Contains HTML class for a text type element
+ *
+ * @package   core_form
+ * @copyright 2006 Jamie Pratt <me@jamiep.org>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 require_once("HTML/QuickForm/text.php");
 
 /**
+ * Text type form element
+ *
  * HTML class for a text type element
  *
- * @author       Jamie Pratt
+ * @package   core_form
- * @access       public
+ * @category  form
+ * @copyright 2006 Jamie Pratt <me@jamiep.org>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class MoodleQuickForm_text extends HTML_QuickForm_text{
-    /**
+    /** @var string html for help button, if empty then no help */
-     * html for help button, if empty then no help
-     *
-     * @var string
-     */
     var $_helpbutton='';
+
+    /** @var bool if true label will be hidden */
     var $_hiddenLabel=false;
 
+    /**
+     * constructor
+     *
+     * @param string $elementName (optional) name of the text field
+     * @param string $elementLabel (optional) text field label
+     * @param string $attributes (optional) Either a typical HTML attribute string or an associative array
+     */
     function MoodleQuickForm_text($elementName=null, $elementLabel=null, $attributes=null) {
         parent::HTML_QuickForm_text($elementName, $elementLabel, $attributes);
     }
 
+    /**
+     * Sets label to be hidden
+     *
+     * @param bool $hiddenLabel sets if label should be hidden
+     */
     function setHiddenLabel($hiddenLabel){
         $this->_hiddenLabel = $hiddenLabel;
     }
+
+    /**
+     * Returns HTML for this form element.
+     *
+     * @return string
+     */
     function toHtml(){
         if ($this->_hiddenLabel){
             $this->_generateId();
@@ -36,22 +82,25 @@ class MoodleQuickForm_text extends HTML_QuickForm_text{
     /**
      * set html for help button
      *
-     * @access   public
+     * @param array $helpbuttonargs array of arguments to make a help button
-     * @param array $help array of arguments to make a help button
      * @param string $function function name to call to get html
+     * @deprecated since Moodle 2.0. Please do not call this function any more.
+     * @todo MDL-31047 this api will be removed.
+     * @see MoodleQuickForm::setHelpButton()
      */
     function setHelpButton($helpbuttonargs, $function='helpbutton'){
         debugging('component setHelpButton() is not used any more, please use $mform->setHelpButton() instead');
     }
+
     /**
      * get html for help button
      *
-     * @access   public
+     * @return string html for help button
-     * @return  string html for help button
      */
     function getHelpButton(){
         return $this->_helpbutton;
     }
+
     /**
      * Slightly different container template when frozen. Don't want to use a label tag
      * with a for attribute in that case for the element label but instead use a div.

lib/form/textarea.php

@@ -1,55 +1,99 @@
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+
+/**
+ * Textarea type form element
+ *
+ * Contains HTML class for a textarea type element
+ *
+ * @package   core_form
+ * @copyright 2006 Jamie Pratt <me@jamiep.org>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 require_once('HTML/QuickForm/textarea.php');
 
 /**
+ * Textarea type form element
+ *
  * HTML class for a textarea type element
  *
- * @author       Jamie Pratt
+ * @package   core_form
- * @access       public
+ * @category  form
+ * @copyright 2006 Jamie Pratt <me@jamiep.org>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class MoodleQuickForm_textarea extends HTML_QuickForm_textarea{
-    /**
+    /** @var string Need to store id of form as we may need it for helpbutton */
-     * Need to store id of form as we may need it for helpbutton
-     *
-     * @var string
-     */
     var $_formid = '';
-    /**
+
-     * html for help button, if empty then no help
+    /** @var string html for help button, if empty then no help */
-     *
-     * @var string
-     */
     var $_helpbutton='';
 
+    /** @var bool if true label will be hidden */
     var $_hiddenLabel=false;
 
+    /**
+     * constructor
+     *
+     * @param string $elementName (optional) name of the text field
+     * @param string $elementLabel (optional) text field label
+     * @param string $attributes (optional) Either a typical HTML attribute string or an associative array
+     */
     function MoodleQuickForm_textarea($elementName=null, $elementLabel=null, $attributes=null) {
         parent::HTML_QuickForm_textarea($elementName, $elementLabel, $attributes);
     }
+
     /**
      * set html for help button
      *
-     * @access   public
+     * @param array $helpbuttonargs array of arguments to make a help button
-     * @param array $help array of arguments to make a help button
      * @param string $function function name to call to get html
+     * @deprecated since Moodle 2.0. Please do not call this function any more.
+     * @todo MDL-31047 this api will be removed.
+     * @see MoodleQuickForm::setHelpButton()
      */
     function setHelpButton($helpbuttonargs, $function='helpbutton'){
         debugging('component setHelpButton() is not used any more, please use $mform->setHelpButton() instead');
     }
+
     /**
      * get html for help button
      *
-     * @access   public
+     * @return string html for help button
-     * @return  string html for help button
      */
     function getHelpButton(){
         return $this->_helpbutton;
     }
 
+    /**
+     * Sets label to be hidden
+     *
+     * @param bool $hiddenLabel sets if label should be hidden
+     */
     function setHiddenLabel($hiddenLabel){
         $this->_hiddenLabel = $hiddenLabel;
     }
 
+    /**
+     * Returns HTML for this form element.
+     *
+     * @return string
+     */
     function toHtml(){
         if ($this->_hiddenLabel){
             $this->_generateId();
@@ -63,12 +107,9 @@ class MoodleQuickForm_textarea extends HTML_QuickForm_textarea{
     /**
      * Called by HTML_QuickForm whenever form event is made on this element
      *
-     * @param     string    $event  Name of event
+     * @param string $event Name of event
-     * @param     mixed     $arg    event arguments
+     * @param mixed $arg event arguments
-     * @param     object    $caller calling object
+     * @param object $caller calling object
-     * @since     1.0
-     * @access    public
-     * @return    void
      */
     function onQuickFormEvent($event, $arg, &$caller)
     {
@@ -78,7 +119,8 @@ class MoodleQuickForm_textarea extends HTML_QuickForm_textarea{
                 break;
         }
         return parent::onQuickFormEvent($event, $arg, $caller);
-    } // end func onQuickFormEvent
+    }
+
     /**
      * Slightly different container template when frozen.
      *

lib/form/url.php

@@ -1,21 +1,56 @@
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+
+/**
+ * url type form element
+ *
+ * Contains HTML class for a url type element
+ *
+ * @package   core_form
+ * @copyright 2009 Dongsheng Cai <dongsheng@moodle.com>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 require_once("HTML/QuickForm/text.php");
 
 /**
- * HTML class for a url type element
+ * url type form element
  *
- * @author       Jamie Pratt
+ * HTML class for a url type element
- * @access       public
+ * @package   core_form
+ * @category  form
+ * @copyright 2009 Dongsheng Cai <dongsheng@moodle.com>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class MoodleQuickForm_url extends HTML_QuickForm_text{
-    /**
+    /** @var string html for help button, if empty then no help */
-     * html for help button, if empty then no help
-     *
-     * @var string
-     */
     var $_helpbutton='';
+
+    /** @var bool if true label will be hidden */
     var $_hiddenLabel=false;
 
+    /**
+     * Constructor
+     *
+     * @param string $elementName Element name
+     * @param mixed $elementLabel Label(s) for an element
+     * @param mixed $attributes Either a typical HTML attribute string or an associative array.
+     * @param array $options data which need to be posted.
+     */
     function MoodleQuickForm_url($elementName=null, $elementLabel=null, $attributes=null, $options=null) {
         global $CFG;
         require_once("$CFG->dirroot/repository/lib.php");
@@ -29,9 +64,20 @@ class MoodleQuickForm_url extends HTML_QuickForm_text{
         parent::HTML_QuickForm_text($elementName, $elementLabel, $attributes);
     }
 
+    /**
+     * Sets label to be hidden
+     *
+     * @param bool $hiddenLabel sets if label should be hidden
+     */
     function setHiddenLabel($hiddenLabel){
         $this->_hiddenLabel = $hiddenLabel;
     }
+
+    /**
+     * Returns HTML for this form element.
+     *
+     * @return string
+     */
     function toHtml(){
         global $CFG, $COURSE, $USER, $PAGE, $OUTPUT;
 
@@ -84,22 +130,25 @@ EOD;
     /**
      * set html for help button
      *
-     * @access   public
+     * @param array $helpbuttonargs array of arguments to make a help button
-     * @param array $help array of arguments to make a help button
      * @param string $function function name to call to get html
+     * @deprecated since Moodle 2.0. Please do not call this function any more.
+     * @todo MDL-31047 this api will be removed.
+     * @see MoodleQuickForm::setHelpButton()
      */
     function setHelpButton($helpbuttonargs, $function='helpbutton'){
         debugging('component setHelpButton() is not used any more, please use $mform->setHelpButton() instead');
     }
+
     /**
      * get html for help button
      *
-     * @access   public
+     * @return string html for help button
-     * @return  string html for help button
      */
     function getHelpButton(){
         return $this->_helpbutton;
     }
+
     /**
      * Slightly different container template when frozen. Don't want to use a label tag
      * with a for attribute in that case for the element label but instead use a div.

lib/form/warning.php

@@ -1,22 +1,58 @@
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+
+/**
+ * static warning element
+ *
+ * Contains class for static warning type element
+ *
+ * @package   core_form
+ * @copyright 2008 Jamie Pratt <me@jamiep.org>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 require_once("HTML/QuickForm/static.php");
 
 /**
- * HTML class for a text type element
+ * static warning
  *
- * @author       Jamie Pratt
+ * overrides {@see HTML_QuickForm_static} to display staic warning.
- * @access       public
+ *
+ * @package   core_form
+ * @category  form
+ * @copyright 2008 Jamie Pratt <me@jamiep.org>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class MoodleQuickForm_warning extends HTML_QuickForm_static{
+    /** @var string Form element type */
     var $_elementTemplateType='warning';
-    /**
+
-     * html for help button, if empty then no help
+    /** @var string html for help button, if empty then no help */
-     *
-     * @var string
-     */
     var $_helpbutton='';
+
+    /** @var string class assigned to field, default is notifyproblem */
     var $_class='';
 
+    /**
+     * constructor
+     *
+     * @param string $elementName (optional) name of the field
+     * @param string $elementClass (optional) show as warning or notification => 'notifyproblem'
+     * @param string $text (optional) Text to put in warning field
+     */
     function MoodleQuickForm_warning($elementName=null, $elementClass='notifyproblem', $text=null) {
         parent::HTML_QuickForm_static($elementName, null, $text);
         $this->_type = 'warning';
@@ -29,14 +65,21 @@ class MoodleQuickForm_warning extends HTML_QuickForm_static{
     /**
      * set html for help button
      *
-     * @access   public
+     * @param array $helpbuttonargs array of arguments to make a help button
-     * @param array $help array of arguments to make a help button
      * @param string $function function name to call to get html
+     * @deprecated since Moodle 2.0. Please do not call this function any more.
+     * @todo MDL-31047 this api will be removed.
+     * @see MoodleQuickForm::setHelpButton()
      */
     function setHelpButton($helpbuttonargs, $function='helpbutton'){
         debugging('component setHelpButton() is not used any more, please use $mform->setHelpButton() instead');
     }
 
+    /**
+     * Returns HTML for this form element.
+     *
+     * @return string
+     */
     function toHtml() {
         global $OUTPUT;
         return $OUTPUT->notification($this->_text, $this->_class);
@@ -45,13 +88,17 @@ class MoodleQuickForm_warning extends HTML_QuickForm_static{
     /**
      * get html for help button
      *
-     * @access   public
+     * @return string html for help button
-     * @return  string html for help button
      */
     function getHelpButton(){
         return $this->_helpbutton;
     }
 
+    /**
+     * Gets the type of form element
+     *
+     * @return string
+     */
     function getElementTemplateType(){
         return $this->_elementTemplateType;
     }