Merge branch 'wip-MDL-30979-m23' of git://github.com/samhemelryk/moodle
authorEloy Lafuente (stronk7) <stronk7@moodle.org>
Mon, 20 Feb 2012 10:38:20 +0000 (11:38 +0100)
committerEloy Lafuente (stronk7) <stronk7@moodle.org>
Mon, 20 Feb 2012 10:38:20 +0000 (11:38 +0100)
lib/outputactions.php
lib/outputcomponents.php
lib/outputfactories.php
lib/outputlib.php
lib/outputrenderers.php
lib/outputrequirementslib.php

index cd5dad4..12c10c3 100644 (file)
@@ -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
  * Please see http://docs.moodle.org/en/Developement:How_Moodle_outputs_HTML
  * for an overview.
  *
- * @package    core
- * @subpackage lib
- * @copyright  2009 Nicolas Connault
- * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @package core
+ * @category output
+ * @copyright 2009 Nicolas Connault
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 defined('MOODLE_INTERNAL') || die();
@@ -33,38 +32,36 @@ defined('MOODLE_INTERNAL') || die();
  * Helper class used by other components that involve an action on the page (URL or JS).
  *
  * @copyright 2009 Nicolas Connault
- * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since     Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
  */
 class component_action {
 
     /**
-     * The DOM event that will trigger this action when caught
-     * @var string $event DOM event
+     * @var string $event The DOM event that will trigger this action when caught
      */
     public $event;
 
     /**
+     * @var string A function name to call when the button is clicked
      * The JS function you create must have two arguments:
      *      1. The event object
      *      2. An object/array of arguments ($jsfunctionargs)
-     * @var string $jsfunction A function name to call when the button is clicked
      */
     public $jsfunction = false;
 
     /**
-     * @var array $jsfunctionargs An array of arguments to pass to the JS function
+     * @var array An array of arguments to pass to the JS function
      */
     public $jsfunctionargs = array();
 
     /**
      * Constructor
      * @param string $event DOM event
-     * @param moodle_url $url A moodle_url object, required if no jsfunction is given
-     * @param string $method 'post' or 'get'
      * @param string $jsfunction An optional JS function. Required if jsfunctionargs is given
-     * @param array  $jsfunctionargs An array of arguments to pass to the jsfunction
-     * @return void
+     * @param array $jsfunctionargs An array of arguments to pass to the jsfunction
      */
     public function __construct($event, $jsfunction, $jsfunctionargs=array()) {
         $this->event = $event;
@@ -83,8 +80,23 @@ class component_action {
 
 /**
  * Confirm action
+ *
+ * @copyright 2009 Nicolas Connault
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
  */
 class confirm_action extends component_action {
+    /**
+     * Constructs the confirm action object
+     *
+     * @param string $message The message to display to the user when they are shown
+     *    the confirm dialogue.
+     * @param string $callback The method to call when the user confirms the action.
+     * @param string $continuelabel The string to use for he continue button
+     * @param string $cancellabel The string to use for the cancel button
+     */
     public function __construct($message, $callback = null, $continuelabel = null, $cancellabel = null) {
         parent::__construct('click', 'M.util.show_confirm_dialog', array(
                 'message' => $message, 'callback' => $callback,
@@ -97,15 +109,20 @@ class confirm_action extends component_action {
  * Component action for a popup window.
  *
  * @copyright 2009 Nicolas Connault
- * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since     Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
  */
 class popup_action extends component_action {
 
+    /**
+     * @var string The JS function to call for the popup
+     */
     public $jsfunction = 'openpopup';
 
     /**
-     * @var array $params An array of parameters that will be passed to the openpopup JS function
+     * @var array An array of parameters that will be passed to the openpopup JS function
      */
     public $params = array(
             'height' =>  400,
@@ -124,11 +141,11 @@ class popup_action extends component_action {
 
     /**
      * Constructor
+     *
      * @param string $event DOM event
      * @param moodle_url|string $url A moodle_url object, required if no jsfunction is given
-     * @param string $method 'post' or 'get'
+     * @param string $name The JS function to call for the popup (default 'popup')
      * @param array  $params An array of popup parameters
-     * @return void
      */
     public function __construct($event, $url, $name='popup', $params=array()) {
         global $CFG;
index f87c4ac..3aef7e7 100644 (file)
@@ -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
  * Please see http://docs.moodle.org/en/Developement:How_Moodle_outputs_HTML
  * for an overview.
  *
- * @package    core
- * @subpackage lib
- * @copyright  2009 Tim Hunt
- * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @package core
+ * @category output
+ * @copyright 2009 Tim Hunt
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 defined('MOODLE_INTERNAL') || die();
 
 /**
  * Interface marking other classes as suitable for renderer_base::render()
- * @author 2010 Petr Skoda (skodak) info@skodak.org
+ *
+ * @copyright 2010 Petr Skoda (skodak) info@skodak.org
+ * @package core
+ * @category output
  */
 interface renderable {
     // intentionally empty
@@ -41,11 +43,33 @@ interface renderable {
  * Data structure representing a file picker.
  *
  * @copyright 2010 Dongsheng Cai
- * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since     Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
  */
 class file_picker implements renderable {
+
+    /**
+     * @var stdClass An object containing options for the file picker
+     */
     public $options;
+
+    /**
+     * Constructs a file picker object.
+     *
+     * The following are possible options for the filepicker:
+     *    - accepted_types  (*)
+     *    - return_types    (FILE_INTERNAL)
+     *    - env             (filepicker)
+     *    - client_id       (uniqid)
+     *    - itemid          (0)
+     *    - maxbytes        (-1)
+     *    - maxfiles        (1)
+     *    - buttonname      (false)
+     *
+     * @param stdClass $options An object containing options for the file picker.
+     */
     public function __construct(stdClass $options) {
         global $CFG, $USER, $PAGE;
         require_once($CFG->dirroot. '/repository/lib.php');
@@ -97,41 +121,53 @@ class file_picker implements renderable {
  * Data structure representing a user picture.
  *
  * @copyright 2009 Nicolas Connault, 2010 Petr Skoda
- * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since     Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Modle 2.0
+ * @package core
+ * @category output
  */
 class user_picture implements renderable {
     /**
-     * @var array List of mandatory fields in user record here. (do not include TEXT columns because it would break SELECT DISTINCT in MSSQL and ORACLE)
+     * @var array List of mandatory fields in user record here. (do not include
+     * TEXT columns because it would break SELECT DISTINCT in MSSQL and ORACLE)
      */
-    protected static $fields = array('id', 'picture', 'firstname', 'lastname', 'imagealt', 'email'); //TODO: add deleted
+    protected static $fields = array('id', 'picture', 'firstname', 'lastname', 'imagealt', 'email');
 
     /**
-     * @var object $user A user object with at least fields all columns specified in $fields array constant set.
+     * @var stdClass A user object with at least fields all columns specified
+     * in $fields array constant set.
      */
     public $user;
+
     /**
-     * @var int $courseid The course id. Used when constructing the link to the user's profile,
-     * page course id used if not specified.
+     * @var int The course id. Used when constructing the link to the user's
+     * profile, page course id used if not specified.
      */
     public $courseid;
+
     /**
-     * @var bool $link add course profile link to image
+     * @var bool Add course profile link to image
      */
     public $link = true;
+
     /**
-     * @var int $size Size in pixels. Special values are (true/1 = 100px) and (false/0 = 35px) for backward compatibility
+     * @var int Size in pixels. Special values are (true/1 = 100px) and
+     * (false/0 = 35px)
+     * for backward compatibility.
      */
     public $size = 35;
+
     /**
-     * @var boolean $alttext add non-blank alt-text to the image.
+     * @var bool Add non-blank alt-text to the image.
      * Default true, set to false when image alt just duplicates text in screenreaders.
      */
     public $alttext = true;
+
     /**
-     * @var boolean $popup Whether or not to open the link in a popup window.
+     * @var bool Whether or not to open the link in a popup window.
      */
     public $popup = false;
+
     /**
      * @var string Image class attribute
      */
@@ -140,8 +176,7 @@ class user_picture implements renderable {
     /**
      * User picture constructor.
      *
-     * @param object $user user record with at least id, picture, imagealt, firstname and lastname set.
-     * @param array $options such as link, size, link, ...
+     * @param stdClass $user user record with at least id, picture, imagealt, firstname and lastname set.
      */
     public function __construct(stdClass $user) {
         global $DB;
@@ -228,7 +263,7 @@ class user_picture implements renderable {
      * @param string $fieldprefix prefix added to all columns in their aliases, does not apply to 'id'
      * @return stdClass object with unaliased user fields
      */
-    public static function unalias(stdClass $record, array $extrafields=null, $idalias='id', $fieldprefix='') {
+    public static function unalias(stdClass $record, array $extrafields = null, $idalias = 'id', $fieldprefix = '') {
 
         if (empty($idalias)) {
             $idalias = 'id';
@@ -266,6 +301,7 @@ class user_picture implements renderable {
      * This method is recommended as it avoids costly redirects of user pictures
      * if requests are made for non-existent files etc.
      *
+     * @param moodle_page $page
      * @param renderer_base $renderer
      * @return moodle_url
      */
@@ -347,34 +383,39 @@ class user_picture implements renderable {
  * Data structure representing a help icon.
  *
  * @copyright 2009 Nicolas Connault, 2010 Petr Skoda
- * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since     Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
  */
 class old_help_icon implements renderable {
+
     /**
-     * @var string $helpidentifier lang pack identifier
+     * @var string Lang pack identifier
      */
     public $helpidentifier;
+
     /**
-     * @var string $title A descriptive text for title tooltip
+     * @var string A descriptive text for title tooltip
      */
     public $title = null;
+
     /**
-     * @var string $component Component name, the same as in get_string()
+     * @var string Component name, the same as in get_string()
      */
     public $component = 'moodle';
+
     /**
-     * @var string $linktext Extra descriptive text next to the icon
+     * @var string Extra descriptive text next to the icon
      */
     public $linktext = null;
 
     /**
      * Constructor: sets up the other components in case they are needed
+     *
      * @param string $helpidentifier  The keyword that defines a help page
      * @param string $title A descriptive text for accessibility only
      * @param string $component
-     * @param bool $linktext add extra text to icon
-     * @return void
      */
     public function __construct($helpidentifier, $title, $component = 'moodle') {
         if (empty($title)) {
@@ -394,28 +435,34 @@ class old_help_icon implements renderable {
  * Data structure representing a help icon.
  *
  * @copyright 2010 Petr Skoda (info@skodak.org)
- * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since     Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
  */
 class help_icon implements renderable {
+
     /**
-     * @var string $identifier lang pack identifier (without the "_help" suffix),
-     *    both get_string($identifier, $component) and get_string($identifier.'_help', $component)
-     *    must exist.
+     * @var string lang pack identifier (without the "_help" suffix),
+     * both get_string($identifier, $component) and get_string($identifier.'_help', $component)
+     * must exist.
      */
     public $identifier;
+
     /**
-     * @var string $component Component name, the same as in get_string()
+     * @var string Component name, the same as in get_string()
      */
     public $component;
+
     /**
-     * @var string $linktext Extra descriptive text next to the icon
+     * @var string Extra descriptive text next to the icon
      */
     public $linktext = null;
 
     /**
      * Constructor
-     * @param string $identifier  string for help page title,
+     *
+     * @param string $identifier string for help page title,
      *  string with _help suffix is used for the actual help text.
      *  string with _link suffix is used to create a link to further info (if it exists)
      * @param string $component
@@ -444,16 +491,31 @@ class help_icon implements renderable {
  * Data structure representing an icon.
  *
  * @copyright 2010 Petr Skoda
- * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since     Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
  */
 class pix_icon implements renderable {
+
+    /**
+     * @var string The icon name
+     */
     var $pix;
+
+    /**
+     * @var string The component the icon belongs to.
+     */
     var $component;
+
+    /**
+     * @var array An array of attributes to use on the icon
+     */
     var $attributes = array();
 
     /**
      * Constructor
+     *
      * @param string $pix short icon name
      * @param string $alt The alt text to use for the icon
      * @param string $component component name
@@ -477,7 +539,11 @@ class pix_icon implements renderable {
 /**
  * Data structure representing an emoticon image
  *
- * @since     Moodle 2.0
+ * @copyright 2010 David Mudrak
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
  */
 class pix_emoticon extends pix_icon implements renderable {
 
@@ -500,54 +566,56 @@ class pix_emoticon extends pix_icon implements renderable {
  * Data structure representing a simple form with only one button.
  *
  * @copyright 2009 Petr Skoda
- * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since     Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
  */
 class single_button implements renderable {
+
     /**
-     * Target url
-     * @var moodle_url
+     * @var moodle_url Target url
      */
     var $url;
+
     /**
-     * Button label
-     * @var string
+     * @var string Button label
      */
     var $label;
+
     /**
-     * Form submit method
-     * @var string post or get
+     * @var string Form submit method post or get
      */
     var $method = 'post';
+
     /**
-     * Wrapping div class
-     * @var string
-     * */
+     * @var string Wrapping div class
+     */
     var $class = 'singlebutton';
+
     /**
-     * True if button disabled, false if normal
-     * @var boolean
+     * @var bool True if button disabled, false if normal
      */
     var $disabled = false;
+
     /**
-     * Button tooltip
-     * @var string
+     * @var string Button tooltip
      */
     var $tooltip = null;
+
     /**
-     * Form id
-     * @var string
+     * @var string Form id
      */
     var $formid;
+
     /**
-     * List of attached actions
-     * @var array of component_action
+     * @var array List of attached actions
      */
     var $actions = array();
 
     /**
      * Constructor
-     * @param string|moodle_url $url
+     * @param moodle_url $url
      * @param string $label button text
      * @param string $method get or post submit method
      */
@@ -560,8 +628,8 @@ class single_button implements renderable {
     /**
      * Shortcut for adding a JS confirm dialog when the button is clicked.
      * The message must be a yes/no question.
-     * @param string $message The yes/no confirmation question. If "Yes" is clicked, the original action will occur.
-     * @return void
+     *
+     * @param string $confirmmessage The yes/no confirmation question. If "Yes" is clicked, the original action will occur.
      */
     public function add_confirm_action($confirmmessage) {
         $this->add_action(new confirm_action($confirmmessage));
@@ -570,7 +638,6 @@ class single_button implements renderable {
     /**
      * Add action to the button.
      * @param component_action $action
-     * @return void
      */
     public function add_action(component_action $action) {
         $this->actions[] = $action;
@@ -580,81 +647,85 @@ class single_button implements renderable {
 
 /**
  * Simple form with just one select field that gets submitted automatically.
+ *
  * If JS not enabled small go button is printed too.
  *
  * @copyright 2009 Petr Skoda
- * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since     Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
  */
 class single_select implements renderable {
+
     /**
-     * Target url - includes hidden fields
-     * @var moodle_url
+     * @var moodle_url Target url - includes hidden fields
      */
     var $url;
+
     /**
-     * Name of the select element.
-     * @var string
+     * @var string Name of the select element.
      */
     var $name;
+
     /**
-     * @var array $options associative array value=>label ex.:
-     *              array(1=>'One, 2=>Two)
-     *              it is also possible to specify optgroup as complex label array ex.:
-     *                array(array('Odd'=>array(1=>'One', 3=>'Three)), array('Even'=>array(2=>'Two')))
-     *                array(1=>'One', '--1uniquekey'=>array('More'=>array(2=>'Two', 3=>'Three')))
+     * @var array $options associative array value=>label ex.: array(1=>'One, 2=>Two)
+     *     it is also possible to specify optgroup as complex label array ex.:
+     *         array(array('Odd'=>array(1=>'One', 3=>'Three)), array('Even'=>array(2=>'Two')))
+     *         array(1=>'One', '--1uniquekey'=>array('More'=>array(2=>'Two', 3=>'Three')))
      */
     var $options;
+
     /**
-     * Selected option
-     * @var string
+     * @var string Selected option
      */
     var $selected;
+
     /**
-     * Nothing selected
-     * @var array
+     * @var array Nothing selected
      */
     var $nothing;
+
     /**
-     * Extra select field attributes
-     * @var array
+     * @var array Extra select field attributes
      */
     var $attributes = array();
+
     /**
-     * Button label
-     * @var string
+     * @var string Button label
      */
     var $label = '';
+
     /**
-     * Form submit method
-     * @var string post or get
+     * @var string Form submit method post or get
      */
     var $method = 'get';
+
     /**
-     * Wrapping div class
-     * @var string
-     * */
+     * @var string Wrapping div class
+     */
     var $class = 'singleselect';
+
     /**
-     * True if button disabled, false if normal
-     * @var boolean
+     * @var bool True if button disabled, false if normal
      */
     var $disabled = false;
+
     /**
-     * Button tooltip
-     * @var string
+     * @var string Button tooltip
      */
     var $tooltip = null;
+
     /**
-     * Form id
-     * @var string
+     * @var string Form id
      */
     var $formid = null;
+
     /**
-     * List of attached actions
-     * @var array of component_action
+     * @var array List of attached actions
      */
     var $helpicon = null;
+
     /**
      * Constructor
      * @param moodle_url $url form action target, includes hidden fields
@@ -664,7 +735,7 @@ class single_select implements renderable {
      * @param array $nothing
      * @param string $formid
      */
-    public function __construct(moodle_url $url, $name, array $options, $selected='', $nothing=array(''=>'choosedots'), $formid=null) {
+    public function __construct(moodle_url $url, $name, array $options, $selected = '', $nothing = array('' => 'choosedots'), $formid = null) {
         $this->url      = $url;
         $this->name     = $name;
         $this->options  = $options;
@@ -676,8 +747,8 @@ class single_select implements renderable {
     /**
      * Shortcut for adding a JS confirm dialog when the button is clicked.
      * The message must be a yes/no question.
-     * @param string $message The yes/no confirmation question. If "Yes" is clicked, the original action will occur.
-     * @return void
+     *
+     * @param string $confirmmessage The yes/no confirmation question. If "Yes" is clicked, the original action will occur.
      */
     public function add_confirm_action($confirmmessage) {
         $this->add_action(new component_action('submit', 'M.util.show_confirm_dialog', array('message' => $confirmmessage)));
@@ -685,8 +756,8 @@ class single_select implements renderable {
 
     /**
      * Add action to the button.
+     *
      * @param component_action $action
-     * @return void
      */
     public function add_action(component_action $action) {
         $this->actions[] = $action;
@@ -694,11 +765,10 @@ class single_select implements renderable {
 
     /**
      * Adds help icon.
-     * @param string $page  The keyword that defines a help page
+     *
+     * @param string $helppage  The keyword that defines a help page
      * @param string $title A descriptive text for accessibility only
      * @param string $component
-     * @param bool $linktext add extra text to icon
-     * @return void
      */
     public function set_old_help_icon($helppage, $title, $component = 'moodle') {
         $this->helpicon = new old_help_icon($helppage, $title, $component);
@@ -706,10 +776,9 @@ class single_select implements renderable {
 
     /**
      * Adds help icon.
+     *
      * @param string $identifier The keyword that defines a help page
      * @param string $component
-     * @param bool $linktext add extra text to icon
-     * @return void
      */
     public function set_help_icon($identifier, $component = 'moodle') {
         $this->helpicon = new help_icon($identifier, $component);
@@ -717,79 +786,82 @@ class single_select implements renderable {
 
     /**
      * Sets select's label
+     *
      * @param string $label
-     * @return void
      */
     public function set_label($label) {
         $this->label = $label;
     }
 }
 
-
 /**
  * Simple URL selection widget description.
+ *
  * @copyright 2009 Petr Skoda
- * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since     Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
  */
 class url_select implements renderable {
     /**
-     * @var array $urls associative array value=>label ex.:
-     *              array(1=>'One, 2=>Two)
-     *              it is also possible to specify optgroup as complex label array ex.:
-     *                array(array('Odd'=>array(1=>'One', 3=>'Three)), array('Even'=>array(2=>'Two')))
-     *                array(1=>'One', '--1uniquekey'=>array('More'=>array(2=>'Two', 3=>'Three')))
+     * @var array $urls associative array value=>label ex.: array(1=>'One, 2=>Two)
+     *     it is also possible to specify optgroup as complex label array ex.:
+     *         array(array('Odd'=>array(1=>'One', 3=>'Three)), array('Even'=>array(2=>'Two')))
+     *         array(1=>'One', '--1uniquekey'=>array('More'=>array(2=>'Two', 3=>'Three')))
      */
     var $urls;
+
     /**
-     * Selected option
-     * @var string
+     * @var string Selected option
      */
     var $selected;
+
     /**
-     * Nothing selected
-     * @var array
+     * @var array Nothing selected
      */
     var $nothing;
+
     /**
-     * Extra select field attributes
-     * @var array
+     * @var array Extra select field attributes
      */
     var $attributes = array();
+
     /**
-     * Button label
-     * @var string
+     * @var string Button label
      */
     var $label = '';
+
     /**
-     * Wrapping div class
-     * @var string
-     * */
+     * @var string Wrapping div class
+     */
     var $class = 'urlselect';
+
     /**
-     * True if button disabled, false if normal
-     * @var boolean
+     * @var bool True if button disabled, false if normal
      */
     var $disabled = false;
+
     /**
-     * Button tooltip
-     * @var string
+     * @var string Button tooltip
      */
     var $tooltip = null;
+
     /**
-     * Form id
-     * @var string
+     * @var string Form id
      */
     var $formid = null;
+
     /**
-     * List of attached actions
-     * @var array of component_action
+     * @var array List of attached actions
      */
     var $helpicon = null;
+
     /**
      * @var string If set, makes button visible with given name for button
      */
     var $showbutton = null;
+
     /**
      * Constructor
      * @param array $urls list of options
@@ -799,8 +871,7 @@ class url_select implements renderable {
      * @param string $showbutton Set to text of button if it should be visible
      *   or null if it should be hidden (hidden version always has text 'go')
      */
-    public function __construct(array $urls, $selected='', $nothing=array(''=>'choosedots'),
-            $formid=null, $showbutton=null) {
+    public function __construct(array $urls, $selected = '', $nothing = array('' => 'choosedots'), $formid = null, $showbutton = null) {
         $this->urls       = $urls;
         $this->selected   = $selected;
         $this->nothing    = $nothing;
@@ -810,11 +881,10 @@ class url_select implements renderable {
 
     /**
      * Adds help icon.
-     * @param string $page  The keyword that defines a help page
+     *
+     * @param string $helppage  The keyword that defines a help page
      * @param string $title A descriptive text for accessibility only
      * @param string $component
-     * @param bool $linktext add extra text to icon
-     * @return void
      */
     public function set_old_help_icon($helppage, $title, $component = 'moodle') {
         $this->helpicon = new old_help_icon($helppage, $title, $component);
@@ -822,10 +892,9 @@ class url_select implements renderable {
 
     /**
      * Adds help icon.
+     *
      * @param string $identifier The keyword that defines a help page
      * @param string $component
-     * @param bool $linktext add extra text to icon
-     * @return void
      */
     public function set_help_icon($identifier, $component = 'moodle') {
         $this->helpicon = new help_icon($identifier, $component);
@@ -833,53 +902,55 @@ class url_select implements renderable {
 
     /**
      * Sets select's label
+     *
      * @param string $label
-     * @return void
      */
     public function set_label($label) {
         $this->label = $label;
     }
 }
 
-
 /**
  * Data structure describing html link with special action attached.
+ *
  * @copyright 2010 Petr Skoda
- * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since     Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
  */
 class action_link implements renderable {
+
     /**
-     * Href url
-     * @var moodle_url
+     * @var moodle_url Href url
      */
     var $url;
+
     /**
-     * Link text
-     * @var string HTML fragment
+     * @var string Link text HTML fragment
      */
     var $text;
+
     /**
-     * HTML attributes
-     * @var array
+     * @var array HTML attributes
      */
     var $attributes;
+
     /**
-     * List of actions attached to link
-     * @var array of component_action
+     * @var array List of actions attached to link
      */
     var $actions;
 
     /**
      * Constructor
-     * @param string|moodle_url $url
+     * @param moodle_url $url
      * @param string $text HTML fragment
      * @param component_action $action
      * @param array $attributes associative array of html link attributes + disabled
      */
-    public function __construct(moodle_url $url, $text, component_action $action=null, array $attributes=null) {
-        $this->url       = clone($url);
-        $this->text      = $text;
+    public function __construct(moodle_url $url, $text, component_action $action = null, array $attributes = null) {
+        $this->url = clone($url);
+        $this->text = $text;
         $this->attributes = (array)$attributes;
         if ($action) {
             $this->add_action($action);
@@ -888,13 +959,17 @@ class action_link implements renderable {
 
     /**
      * Add action to the link.
+     *
      * @param component_action $action
-     * @return void
      */
     public function add_action(component_action $action) {
         $this->actions[] = $action;
     }
 
+    /**
+     * Adds a CSS class to this action link object
+     * @param string $class
+     */
     public function add_class($class) {
         if (empty($this->attributes['class'])) {
             $this->attributes['class'] = $class;
@@ -904,15 +979,20 @@ class action_link implements renderable {
     }
 }
 
-// ==== HTML writer and helper classes, will be probably moved elsewhere ======
-
 /**
  * Simple html output class
+ *
  * @copyright 2009 Tim Hunt, 2010 Petr Skoda
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
  */
 class html_writer {
+
     /**
      * Outputs a tag with attributes and contents
+     *
      * @param string $tagname The name of tag ('a', 'img', 'span' etc.)
      * @param string $contents What goes between the opening and closing tags
      * @param array $attributes The tag attributes (array('src' => $url, 'class' => 'class1') etc.)
@@ -924,6 +1004,7 @@ class html_writer {
 
     /**
      * Outputs an opening tag with attributes
+     *
      * @param string $tagname The name of tag ('a', 'img', 'span' etc.)
      * @param array $attributes The tag attributes (array('src' => $url, 'class' => 'class1') etc.)
      * @return string HTML fragment
@@ -934,6 +1015,7 @@ class html_writer {
 
     /**
      * Outputs a closing tag
+     *
      * @param string $tagname The name of tag ('a', 'img', 'span' etc.)
      * @return string HTML fragment
      */
@@ -943,6 +1025,7 @@ class html_writer {
 
     /**
      * Outputs an empty tag with attributes
+     *
      * @param string $tagname The name of tag ('input', 'img', 'br' etc.)
      * @param array $attributes The tag attributes (array('src' => $url, 'class' => 'class1') etc.)
      * @return string HTML fragment
@@ -953,6 +1036,7 @@ class html_writer {
 
     /**
      * Outputs a tag, but only if the contents are not empty
+     *
      * @param string $tagname The name of tag ('a', 'img', 'span' etc.)
      * @param string $contents What goes between the opening and closing tags
      * @param array $attributes The tag attributes (array('src' => $url, 'class' => 'class1') etc.)
@@ -967,6 +1051,7 @@ class html_writer {
 
     /**
      * Outputs a HTML attribute and value
+     *
      * @param string $name The name of the attribute ('src', 'href', 'class' etc.)
      * @param string $value The value of the attribute. The value will be escaped with {@link s()}
      * @return string HTML fragment
@@ -990,6 +1075,7 @@ class html_writer {
 
     /**
      * Outputs a list of HTML attributes and values
+     *
      * @param array $attributes The tag attributes (array('src' => $url, 'class' => 'class1') etc.)
      *       The values will be escaped with {@link s()}
      * @return string HTML fragment
@@ -1005,8 +1091,11 @@ class html_writer {
 
     /**
      * Generates random html element id.
-     * @param string $base
-     * @return string
+     *
+     * @staticvar int $counter
+     * @staticvar type $uniq
+     * @param string $base A string fragment that will be included in the random ID.
+     * @return string A unique ID
      */
     public static function random_id($base='random') {
         static $counter = 0;
@@ -1022,9 +1111,10 @@ class html_writer {
 
     /**
      * Generates a simple html link
-     * @param string|moodle_url $url
-     * @param string $text link txt
-     * @param array $attributes extra html attributes
+     *
+     * @param string|moodle_url $url The URL
+     * @param string $text The text
+     * @param array $attributes HTML attributes
      * @return string HTML fragment
      */
     public static function link($url, $text, array $attributes = null) {
@@ -1034,12 +1124,13 @@ class html_writer {
     }
 
     /**
-     * generates a simple checkbox with optional label
-     * @param string $name
-     * @param string $value
-     * @param bool $checked
-     * @param string $label
-     * @param array $attributes
+     * Generates a simple checkbox with optional label
+     *
+     * @param string $name The name of the checkbox
+     * @param string $value The value of the checkbox
+     * @param bool $checked Whether the checkbox is checked
+     * @param string $label The label for the checkbox
+     * @param array $attributes Any attributes to apply to the checkbox
      * @return string html fragment
      */
     public static function checkbox($name, $value, $checked = true, $label = '', array $attributes = null) {
@@ -1067,10 +1158,11 @@ class html_writer {
 
     /**
      * Generates a simple select yes/no form field
+     *
      * @param string $name name of select element
      * @param bool $selected
      * @param array $attributes - html select element attributes
-     * @return string HRML fragment
+     * @return string HTML fragment
      */
     public static function select_yes_no($name, $selected=true, array $attributes = null) {
         $options = array('1'=>get_string('yes'), '0'=>get_string('no'));
@@ -1079,6 +1171,7 @@ class html_writer {
 
     /**
      * Generates a simple select form field
+     *
      * @param array $options associative array value=>label ex.:
      *                array(1=>'One, 2=>Two)
      *              it is also possible to specify optgroup as complex label array ex.:
@@ -1086,11 +1179,11 @@ class html_writer {
      *                array(1=>'One', '--1uniquekey'=>array('More'=>array(2=>'Two', 3=>'Three')))
      * @param string $name name of select element
      * @param string|array $selected value or array of values depending on multiple attribute
-     * @param array|bool $nothing, add nothing selected option, or false of not added
-     * @param array $attributes html select element attributes
+     * @param array|bool $nothing add nothing selected option, or false of not added
+     * @param array $attributes html select element attributes
      * @return string HTML fragment
      */
-    public static function select(array $options, $name, $selected = '', $nothing = array(''=>'choosedots'), array $attributes = null) {
+    public static function select(array $options, $name, $selected = '', $nothing = array('' => 'choosedots'), array $attributes = null) {
         $attributes = (array)$attributes;
         if (is_array($nothing)) {
             foreach ($nothing as $k=>$v) {
@@ -1126,7 +1219,7 @@ class html_writer {
             $class = str_replace(']', '', $class);
             $attributes['class'] = $class;
         }
-        $attributes['class'] = 'select ' . $attributes['class']; /// Add 'select' selector always
+        $attributes['class'] = 'select ' . $attributes['class']; // Add 'select' selector always
 
         $attributes['name'] = $name;
 
@@ -1148,6 +1241,14 @@ class html_writer {
         return self::tag('select', $output, $attributes);
     }
 
+    /**
+     * Returns HTML to display a select box option.
+     *
+     * @param string $label The label to display as the option.
+     * @param string|int $value The value the option represents
+     * @param array $selected An array of selected options
+     * @return string HTML fragment
+     */
     private static function select_option($label, $value, array $selected) {
         $attributes = array();
         $value = (string)$value;
@@ -1158,6 +1259,14 @@ class html_writer {
         return self::tag('option', $label, $attributes);
     }
 
+    /**
+     * Returns HTML to display a select box option group.
+     *
+     * @param string $groupname The label to use for the group
+     * @param array $options The options in the group
+     * @param array $selected An array of selected values.
+     * @return string HTML fragment.
+     */
     private static function select_optgroup($groupname, $options, array $selected) {
         if (empty($options)) {
             return '';
@@ -1172,6 +1281,7 @@ class html_writer {
 
     /**
      * This is a shortcut for making an hour selector menu.
+     *
      * @param string $type The type of selector (years, months, days, hours, minutes)
      * @param string $name fieldname
      * @param int $currenttime A default timestamp in GMT
@@ -1179,7 +1289,7 @@ class html_writer {
      * @param array $attributes - html select element attributes
      * @return HTML fragment
      */
-    public static function select_time($type, $name, $currenttime=0, $step=5, array $attributes=null) {
+    public static function select_time($type, $name, $currenttime = 0, $step = 5, array $attributes = null) {
         if (!$currenttime) {
             $currenttime = time();
         }
@@ -1236,14 +1346,15 @@ class html_writer {
 
     /**
      * Shortcut for quick making of lists
+     *
+     * Note: 'list' is a reserved keyword ;-)
+     *
      * @param array $items
-     * @param string $tag ul or ol
      * @param array $attributes
+     * @param string $tag ul or ol
      * @return string
      */
     public static function alist(array $items, array $attributes = null, $tag = 'ul') {
-        //note: 'list' is a reserved keyword ;-)
-
         $output = '';
 
         foreach ($items as $item) {
@@ -1257,6 +1368,7 @@ class html_writer {
 
     /**
      * Returns hidden input fields created from url parameters.
+     *
      * @param moodle_url $url
      * @param array $exclude list of excluded parameters
      * @return string HTML fragment
@@ -1279,8 +1391,8 @@ class html_writer {
     /**
      * Generate a script tag containing the the specified code.
      *
-     * @param string $js the JavaScript code
-        * @param moodle_url|string optional url of the external script, $code ignored if specified
+     * @param string $jscode the JavaScript code
+     * @param moodle_url|string $url optional url of the external script, $code ignored if specified
      * @return string HTML, the code wrapped in <script> tags.
      */
     public static function script($jscode, $url=null) {
@@ -1545,43 +1657,46 @@ class html_writer {
      * @param array $attributes to be inserted in the tab, for example array('accesskey' => 'a')
      * @return string HTML of the label element
      */
-    public static function label($text, $for, $colonize=true, array $attributes=array()) {
+    public static function label($text, $for, $colonize = true, array $attributes=array()) {
         if (!is_null($for)) {
             $attributes = array_merge($attributes, array('for' => $for));
         }
         $text = trim($text);
         $label = self::tag('label', $text, $attributes);
 
-        /*
-        // TODO $colonize disabled for now yet - see MDL-12192 for details
-        if (!empty($text) and $colonize) {
-            // the $text may end with the colon already, though it is bad string definition style
-            $colon = get_string('labelsep', 'langconfig');
-            if (!empty($colon)) {
-                $trimmed = trim($colon);
-                if ((substr($text, -strlen($trimmed)) == $trimmed) or (substr($text, -1) == ':')) {
-                    //debugging('The label text should not end with colon or other label separator,
-                    //           please fix the string definition.', DEBUG_DEVELOPER);
-                } else {
-                    $label .= $colon;
-                }
-            }
-        }
-        */
+        // TODO MDL-12192 $colonize disabled for now yet
+        // if (!empty($text) and $colonize) {
+        //     // the $text may end with the colon already, though it is bad string definition style
+        //     $colon = get_string('labelsep', 'langconfig');
+        //     if (!empty($colon)) {
+        //         $trimmed = trim($colon);
+        //         if ((substr($text, -strlen($trimmed)) == $trimmed) or (substr($text, -1) == ':')) {
+        //             //debugging('The label text should not end with colon or other label separator,
+        //             //           please fix the string definition.', DEBUG_DEVELOPER);
+        //         } else {
+        //             $label .= $colon;
+        //         }
+        //     }
+        // }
 
         return $label;
     }
 }
 
-// ==== JS writer and helper classes, will be probably moved elsewhere ======
-
 /**
  * Simple javascript output class
+ *
  * @copyright 2010 Petr Skoda
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
  */
 class js_writer {
+
     /**
      * Returns javascript code calling the function
+     *
      * @param string $function function name, can be complex like Y.Event.purgeElement
      * @param array $arguments parameters
      * @param int $delay execution delay in seconds
@@ -1604,10 +1719,11 @@ class js_writer {
     }
 
     /**
-     * Special function which adds Y as first argument of fucntion call.
-     * @param string $function
-     * @param array $extraarguments
-     * @return string
+     * Special function which adds Y as first argument of function call.
+     *
+     * @param string $function The function to call
+     * @param array $extraarguments Any arguments to pass to it
+     * @return string Some JS code
      */
     public static function function_call_with_Y($function, array $extraarguments = null) {
         if ($extraarguments) {
@@ -1621,12 +1737,13 @@ class js_writer {
 
     /**
      * Returns JavaScript code to initialise a new object
-     * @param string|null $var If it is null then no var is assigned the new object
-     * @param string $class
-     * @param array $arguments
-     * @param array $requirements
-     * @param int $delay
-     * @return string
+     *
+     * @param string $var If it is null then no var is assigned the new object.
+     * @param string $class The class to initialise an object for.
+     * @param array $arguments An array of args to pass to the init method.
+     * @param array $requirements Any modules required for this class.
+     * @param int $delay The delay before initialisation. 0 = no delay.
+     * @return string Some JS code
      */
     public static function object_init($var, $class, array $arguments = null, array $requirements = null, $delay=0) {
         if (is_array($arguments)) {
@@ -1656,12 +1773,13 @@ class js_writer {
 
     /**
      * Returns code setting value to variable
+     *
      * @param string $name
      * @param mixed $value json serialised value
      * @param bool $usevar add var definition, ignored for nested properties
      * @return string JS code fragment
      */
-    public static function set_variable($name, $value, $usevar=true) {
+    public static function set_variable($name, $value, $usevar = true) {
         $output = '';
 
         if ($usevar) {
@@ -1679,10 +1797,12 @@ class js_writer {
 
     /**
      * Writes event handler attaching code
-     * @param mixed $selector standard YUI selector for elements, may be array or string, element id is in the form "#idvalue"
+     *
+     * @param array|string $selector standard YUI selector for elements, may be
+     *     array or string, element id is in the form "#idvalue"
      * @param string $event A valid DOM event (click, mousedown, change etc.)
      * @param string $function The name of the function to call
-     * @param array  $arguments An optional array of argument parameters to pass to the function
+     * @param array $arguments An optional array of argument parameters to pass to the function
      * @return string JS code fragment
      */
     public static function event_handler($selector, $event, $function, array $arguments = null) {
@@ -1696,7 +1816,7 @@ class js_writer {
 }
 
 /**
- * Holds all the information required to render a <table> by {@see core_renderer::table()}
+ * Holds all the information required to render a <table> by {@link core_renderer::table()}
  *
  * Example of usage:
  * $t = new html_table();
@@ -1704,39 +1824,46 @@ class js_writer {
  * echo html_writer::table($t);
  *
  * @copyright 2009 David Mudrak <david.mudrak@gmail.com>
- * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since     Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
  */
 class html_table {
+
     /**
-     * @var string value to use for the id attribute of the table
+     * @var string Value to use for the id attribute of the table
      */
     public $id = null;
+
     /**
-     * @var array attributes of HTML attributes for the <table> element
+     * @var array Attributes of HTML attributes for the <table> element
      */
     public $attributes = array();
+
     /**
+     * @var array An array of headings. The n-th array item is used as a heading of the n-th column.
      * For more control over the rendering of the headers, an array of html_table_cell objects
      * can be passed instead of an array of strings.
-     * @var array of headings. The n-th array item is used as a heading of the n-th column.
      *
      * Example of usage:
      * $t->head = array('Student', 'Grade');
      */
     public $head;
+
     /**
-     * @var array can be used to make a heading span multiple columns
+     * @var array An array that can be used to make a heading span multiple columns.
+     * In this example, {@link html_table:$data} is supposed to have three columns. For the first two columns,
+     * the same heading is used. Therefore, {@link html_table::$head} should consist of two items.
      *
      * Example of usage:
      * $t->headspan = array(2,1);
-     *
-     * In this example, {@see html_table:$data} is supposed to have three columns. For the first two columns,
-     * the same heading is used. Therefore, {@see html_table::$head} should consist of two items.
      */
     public $headspan;
+
     /**
-     * @var array of column alignments. The value is used as CSS 'text-align' property. Therefore, possible
+     * @var array An array of column alignments.
+     * The value is used as CSS 'text-align' property. Therefore, possible
      * values are 'left', 'right', 'center' and 'justify'. Specify 'right' or 'left' from the perspective
      * of a left-to-right (LTR) language. For RTL, the values are flipped automatically.
      *
@@ -1744,11 +1871,11 @@ class html_table {
      * $t->align = array(null, 'right');
      * or
      * $t->align[1] = 'right';
-     *
      */
     public $align;
+
     /**
-     * @var array of column sizes. The value is used as CSS 'size' property.
+     * @var array The value is used as CSS 'size' property.
      *
      * Examples of usage:
      * $t->size = array('50%', '50%');
@@ -1756,16 +1883,19 @@ class html_table {
      * $t->size[1] = '120px';
      */
     public $size;
+
     /**
-     * @var array of wrapping information. The only possible value is 'nowrap' that sets the
+     * @var array An array of wrapping information.
+     * The only possible value is 'nowrap' that sets the
      * CSS property 'white-space' to the value 'nowrap' in the given column.
      *
      * Example of usage:
      * $t->wrap = array(null, 'nowrap');
      */
     public $wrap;
+
     /**
-     * @var array of arrays or html_table_row objects containing the data. Alternatively, if you have
+     * @var array Array of arrays or html_table_row objects containing the data. Alternatively, if you have
      * $head specified, the string 'hr' (for horizontal ruler) can be used
      * instead of an array of cells data resulting in a divider rendered.
      *
@@ -1789,28 +1919,33 @@ class html_table {
      * $t->data = array($row1, $row2);
      */
     public $data;
+
     /**
-     * @var string width of the table, percentage of the page preferred. Defaults to 80%
      * @deprecated since Moodle 2.0. Styling should be in the CSS.
+     * @var string Width of the table, percentage of the page preferred.
      */
     public $width = null;
+
     /**
-     * @var string alignment the whole table. Can be 'right', 'left' or 'center' (default).
      * @deprecated since Moodle 2.0. Styling should be in the CSS.
+     * @var string Alignment for the whole table. Can be 'right', 'left' or 'center' (default).
      */
     public $tablealign = null;
+
     /**
-     * @var int padding on each cell, in pixels
      * @deprecated since Moodle 2.0. Styling should be in the CSS.
+     * @var int Padding on each cell, in pixels
      */
     public $cellpadding = null;
+
     /**
-     * @var int spacing between cells, in pixels
+     * @var int Spacing between cells, in pixels
      * @deprecated since Moodle 2.0. Styling should be in the CSS.
      */
     public $cellspacing = null;
+
     /**
-     * @var array classes to add to particular rows, space-separated string.
+     * @var array Array of classes to add to particular rows, space-separated string.
      * Classes 'r0' or 'r1' are added automatically for every odd or even row,
      * respectively. Class 'lastrow' is added automatically for the last row
      * in the table.
@@ -1819,8 +1954,9 @@ class html_table {
      * $t->rowclasses[9] = 'tenth'
      */
     public $rowclasses;
+
     /**
-     * @var array classes to add to every cell in a particular column,
+     * @var array An array of classes to add to every cell in a particular column,
      * space-separated string. Class 'cell' is added automatically by the renderer.
      * Classes 'c0' or 'c1' are added automatically for every odd or even column,
      * respectively. Class 'lastcol' is added automatically for all last cells
@@ -1830,8 +1966,9 @@ class html_table {
      * $t->colclasses = array(null, 'grade');
      */
     public $colclasses;
+
     /**
-     * @var string description of the contents for screen readers.
+     * @var string Description of the contents for screen readers.
      */
     public $summary;
 
@@ -1843,29 +1980,34 @@ class html_table {
     }
 }
 
-
 /**
  * Component representing a table row.
  *
  * @copyright 2009 Nicolas Connault
- * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since     Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
  */
 class html_table_row {
+
     /**
-     * @var string value to use for the id attribute of the row
+     * @var string Value to use for the id attribute of the row.
      */
     public $id = null;
+
     /**
-     * @var array $cells Array of html_table_cell objects
+     * @var array Array of html_table_cell objects
      */
     public $cells = array();
+
     /**
-     * @var string $style value to use for the style attribute of the table row
+     * @var string Value to use for the style attribute of the table row
      */
     public $style = null;
+
     /**
-     * @var array attributes of additional HTML attributes for the <tr> element
+     * @var array Attributes of additional HTML attributes for the <tr> element
      */
     public $attributes = array();
 
@@ -1886,113 +2028,140 @@ class html_table_row {
     }
 }
 
-
 /**
  * Component representing a table cell.
  *
  * @copyright 2009 Nicolas Connault
- * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since     Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
  */
 class html_table_cell {
+
     /**
-     * @var string value to use for the id attribute of the cell
+     * @var string Value to use for the id attribute of the cell.
      */
     public $id = null;
+
     /**
-     * @var string $text The contents of the cell
+     * @var string The contents of the cell.
      */
     public $text;
+
     /**
-     * @var string $abbr Abbreviated version of the contents of the cell
+     * @var string Abbreviated version of the contents of the cell.
      */
     public $abbr = null;
+
     /**
-     * @var int $colspan Number of columns this cell should span
+     * @var int Number of columns this cell should span.
      */
     public $colspan = null;
+
     /**
-     * @var int $rowspan Number of rows this cell should span
+     * @var int Number of rows this cell should span.
      */
     public $rowspan = null;
+
     /**
-     * @var string $scope Defines a way to associate header cells and data cells in a table
+     * @var string Defines a way to associate header cells and data cells in a table.
      */
     public $scope = null;
+
     /**
-     * @var boolean $header Whether or not this cell is a header cell
+     * @var bool Whether or not this cell is a header cell.
      */
     public $header = null;
+
     /**
-     * @var string $style value to use for the style attribute of the table cell
+     * @var string Value to use for the style attribute of the table cell
      */
     public $style = null;
+
     /**
-     * @var array attributes of additional HTML attributes for the <td> element
+     * @var array Attributes of additional HTML attributes for the <td> element
      */
     public $attributes = array();
 
+    /**
+     * Constructs a table cell
+     *
+     * @param string $text
+     */
     public function __construct($text = null) {
         $this->text = $text;
         $this->attributes['class'] = '';
     }
 }
 
-
-/// Complex components aggregating simpler components
-
-
 /**
  * Component representing a paging bar.
  *
  * @copyright 2009 Nicolas Connault
- * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since     Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
  */
 class paging_bar implements renderable {
+
     /**
-     * @var int $maxdisplay The maximum number of pagelinks to display
+     * @var int The maximum number of pagelinks to display.
      */
     public $maxdisplay = 18;
+
     /**
-     * @var int $totalcount post or get
+     * @var int The total number of entries to be pages through..
      */
     public $totalcount;
+
     /**
-     * @var int $page The page you are currently viewing
+     * @var int The page you are currently viewing.
      */
     public $page;
+
     /**
-     * @var int $perpage The number of entries that should be shown per page
+     * @var int The number of entries that should be shown per page.
      */
     public $perpage;
+
     /**
-     * @var string $baseurl If this  is a string then it is the url which will be appended with $pagevar, an equals sign and the page number.
-     *      If this is a moodle_url object then the pagevar param will be replaced by the page no, for each page.
+     * @var string|moodle_url If this  is a string then it is the url which will be appended with $pagevar,
+     * an equals sign and the page number.
+     * If this is a moodle_url object then the pagevar param will be replaced by
+     * the page no, for each page.
      */
     public $baseurl;
+
     /**
-     * @var string $pagevar This is the variable name that you use for the page number in your code (ie. 'tablepage', 'blogpage', etc)
+     * @var string This is the variable name that you use for the pagenumber in your
+     * code (ie. 'tablepage', 'blogpage', etc)
      */
     public $pagevar;
+
     /**
-     * @var string $previouslink A HTML link representing the "previous" page
+     * @var string A HTML link representing the "previous" page.
      */
     public $previouslink = null;
+
     /**
-     * @var tring $nextlink A HTML link representing the "next" page
+     * @var string A HTML link representing the "next" page.
      */
     public $nextlink = null;
+
     /**
-     * @var tring $firstlink A HTML link representing the first page
+     * @var string A HTML link representing the first page.
      */
     public $firstlink = null;
+
     /**
-     * @var tring $lastlink A HTML link representing the last page
+     * @var string A HTML link representing the last page.
      */
     public $lastlink = null;
+
     /**
-     * @var array $pagelinks An array of strings. One of them is just a string: the current page
+     * @var array An array of strings. One of them is just a string: the current page
      */
     public $pagelinks = array();
 
@@ -2014,7 +2183,15 @@ class paging_bar implements renderable {
     }
 
     /**
-     * @return void
+     * Prepares the paging bar for output.
+     *
+     * This method validates the arguments set up for the paging bar and then
+     * produces fragments of HTML to assist display later on.
+     *
+     * @param renderer_base $output
+     * @param moodle_page $page
+     * @param string $target
+     * @throws coding_exception
      */
     public function prepare(renderer_base $output, moodle_page $page, $target) {
         if (!isset($this->totalcount) || is_null($this->totalcount)) {
@@ -2082,93 +2259,100 @@ class paging_bar implements renderable {
     }
 }
 
-
 /**
  * This class represents how a block appears on a page.
  *
  * During output, each block instance is asked to return a block_contents object,
  * those are then passed to the $OUTPUT->block function for display.
  *
- * {@link $contents} should probably be generated using a moodle_block_..._renderer.
+ * contents should probably be generated using a moodle_block_..._renderer.
  *
  * Other block-like things that need to appear on the page, for example the
  * add new block UI, are also represented as block_contents objects.
  *
  * @copyright 2009 Tim Hunt
- * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since     Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
  */
 class block_contents {
-    /** @var int used to set $skipid. */
-    protected static $idcounter = 1;
 
+    /** Used when the block cannot be collapsed **/
     const NOT_HIDEABLE = 0;
+
+    /** Used when the block can be collapsed but currently is not **/
     const VISIBLE = 1;
+
+    /** Used when the block has been collapsed **/
     const HIDDEN = 2;
 
     /**
-     * @var integer $skipid All the blocks (or things that look like blocks)
-     * printed on a page are given a unique number that can be used to construct
-     * id="" attributes. This is set automatically be the {@link prepare()} method.
+     * @var int Used to set $skipid.
+     */
+    protected static $idcounter = 1;
+
+    /**
+     * @var int All the blocks (or things that look like blocks) printed on
+     * a page are given a unique number that can be used to construct id="" attributes.
+     * This is set automatically be the {@link prepare()} method.
      * Do not try to set it manually.
      */
     public $skipid;
 
     /**
-     * @var integer If this is the contents of a real block, this should be set to
-     * the block_instance.id. Otherwise this should be set to 0.
+     * @var int If this is the contents of a real block, this should be set
+     * to the block_instance.id. Otherwise this should be set to 0.
      */
     public $blockinstanceid = 0;
 
     /**
-     * @var integer if this is a real block instance, and there is a corresponding
+     * @var int If this is a real block instance, and there is a corresponding
      * block_position.id for the block on this page, this should be set to that id.
      * Otherwise it should be 0.
      */
     public $blockpositionid = 0;
 
     /**
-     * @param array $attributes an array of attribute => value pairs that are put on the
-     * outer div of this block. {@link $id} and {@link $classes} attributes should be set separately.
+     * @var array An array of attribute => value pairs that are put on the outer div of this
+     * block. {@link $id} and {@link $classes} attributes should be set separately.
      */
     public $attributes;
 
     /**
-     * @param string $title The title of this block. If this came from user input,
-     * it should already have had format_string() processing done on it. This will
-     * be output inside <h2> tags. Please do not cause invalid XHTML.
+     * @var string The title of this block. If this came from user input, it should already
+     * have had format_string() processing done on it. This will be output inside
+     * <h2> tags. Please do not cause invalid XHTML.
      */
     public $title = '';
 
     /**
-     * @param string $content HTML for the content
+     * @var string HTML for the content
      */
     public $content = '';
 
     /**
-     * @param array $list an alternative to $content, it you want a list of things with optional icons.
+     * @var array An alternative to $content, it you want a list of things with optional icons.
      */
     public $footer = '';
 
     /**
-     * Any small print that should appear under the block to explain to the
-     * teacher about the block, for example 'This is a sticky block that was
+     * @var string Any small print that should appear under the block to explain
+     * to the teacher about the block, for example 'This is a sticky block that was
      * added in the system context.'
-     * @var string
      */
     public $annotation = '';
 
     /**
-     * @var integer one of the constants NOT_HIDEABLE, VISIBLE, HIDDEN. Whether
+     * @var int One of the constants NOT_HIDEABLE, VISIBLE, HIDDEN. Whether
      * the user can toggle whether this block is visible.
      */
     public $collapsible = self::NOT_HIDEABLE;
 
     /**
-     * A (possibly empty) array of editing controls. Each element of this array
-     * should be an array('url' => $url, 'icon' => $icon, 'caption' => $caption).
+     * @var array A (possibly empty) array of editing controls. Each element of
+     * this array should be an array('url' => $url, 'icon' => $icon, 'caption' => $caption).
      * $icon is the icon name. Fed to $OUTPUT->pix_url.
-     * @var array
      */
     public $controls = array();
 
@@ -2177,7 +2361,7 @@ class block_contents {
      * Create new instance of block content
      * @param array $attributes
      */
-    public function __construct(array $attributes=null) {
+    public function __construct(array $attributes = null) {
         $this->skipid = self::$idcounter;
         self::$idcounter += 1;
 
@@ -2192,8 +2376,8 @@ class block_contents {
 
     /**
      * Add html class to block
+     *
      * @param string $class
-     * @return void
      */
     public function add_class($class) {
         $this->attributes['class'] .= ' '.$class;
@@ -2209,18 +2393,20 @@ class block_contents {
  * $PAGE->url.
  *
  * @copyright 2009 Tim Hunt
- * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since     Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
  */
 class block_move_target {
+
     /**
-     * Move url
-     * @var moodle_url
+     * @var moodle_url Move url
      */
     public $url;
+
     /**
-     * label
-     * @var string
+     * @var string label
      */
     public $text;
 
@@ -2242,45 +2428,50 @@ class block_move_target {
  * not have children.
  *
  * @copyright 2010 Sam Hemelryk
- * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since     Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
  */
 class custom_menu_item implements renderable {
+
     /**
-     * The text to show for the item
-     * @var string
+     * @var string The text to show for the item
      */
     protected $text;
+
     /**
-     * The link to give the icon if it has no children
-     * @var moodle_url
+     * @var moodle_url The link to give the icon if it has no children
      */
     protected $url;
+
     /**
-     * A title to apply to the item. By default the text
-     * @var string
+     * @var string A title to apply to the item. By default the text
      */
     protected $title;
+
     /**
-     * A sort order for the item, not necessary if you order things in the CFG var
-     * @var int
+     * @var int A sort order for the item, not necessary if you order things in
+     * the CFG var.
      */
     protected $sort;
+
     /**
-     * A reference to the parent for this item or NULL if it is a top level item
-     * @var custom_menu_item
+     * @var custom_menu_item A reference to the parent for this item or NULL if
+     * it is a top level item
      */
     protected $parent;
+
     /**
-     * A array in which to store children this item has.
-     * @var array
+     * @var array A array in which to store children this item has.
      */
     protected $children = array();
+
     /**
-     * A reference to the sort var of the last child that was added
-     * @var int
+     * @var int A reference to the sort var of the last child that was added
      */
     protected $lastsort = 0;
+
     /**
      * Constructs the new custom menu item
      *
@@ -2291,7 +2482,7 @@ class custom_menu_item implements renderable {
      * @param custom_menu_item $parent A reference to the parent custom_menu_item this child
      *        belongs to, only if the child has a parent. [Optional]
      */
-    public function __construct($text, moodle_url $url=null, $title=null, $sort = null, custom_menu_item $parent=null) {
+    public function __construct($text, moodle_url $url=null, $title=null, $sort = null, custom_menu_item $parent = null) {
         $this->text = $text;
         $this->url = $url;
         $this->title = $title;
@@ -2308,7 +2499,7 @@ class custom_menu_item implements renderable {
      * @param int $sort
      * @return custom_menu_item
      */
-    public function add($text, moodle_url $url=null, $title=null, $sort = null) {
+    public function add($text, moodle_url $url = null, $title = null, $sort = null) {
         $key = count($this->children);
         if (empty($sort)) {
             $sort = $this->lastsort + 1;
@@ -2317,6 +2508,7 @@ class custom_menu_item implements renderable {
         $this->lastsort = (int)$sort;
         return $this->children[$key];
     }
+
     /**
      * Returns the text for this item
      * @return string
@@ -2324,6 +2516,7 @@ class custom_menu_item implements renderable {
     public function get_text() {
         return $this->text;
     }
+
     /**
      * Returns the url for this item
      * @return moodle_url
@@ -2331,6 +2524,7 @@ class custom_menu_item implements renderable {
     public function get_url() {
         return $this->url;
     }
+
     /**
      * Returns the title for this item
      * @return string
@@ -2338,6 +2532,7 @@ class custom_menu_item implements renderable {
     public function get_title() {
         return $this->title;
     }
+
     /**
      * Sorts and returns the children for this item
      * @return array
@@ -2346,6 +2541,7 @@ class custom_menu_item implements renderable {
         $this->sort();
         return $this->children;
     }
+
     /**
      * Gets the sort order for this child
      * @return int
@@ -2353,6 +2549,7 @@ class custom_menu_item implements renderable {
     public function get_sort_order() {
         return $this->sort;
     }
+
     /**
      * Gets the parent this child belong to
      * @return custom_menu_item
@@ -2360,12 +2557,14 @@ class custom_menu_item implements renderable {
     public function get_parent() {
         return $this->parent;
     }
+
     /**
      * Sorts the children this item has
      */
     public function sort() {
         usort($this->children, array('custom_menu','sort_custom_menu_items'));
     }
+
     /**
      * Returns true if this item has any children
      * @return bool
@@ -2410,22 +2609,25 @@ class custom_menu_item implements renderable {
  *     Settings: Administration > Appearance > Themes > Theme settings
  *
  * @copyright 2010 Sam Hemelryk
- * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since     Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
  */
 class custom_menu extends custom_menu_item {
 
-    /** @var string the language we should render for, null disables multilang support */
+    /**
+     * @var string The language we should render for, null disables multilang support.
+     */
     protected $currentlanguage = null;
 
     /**
      * Creates the custom menu
      *
      * @param string $definition the menu items definition in syntax required by {@link convert_text_to_menu_nodes()}
-     * @param string $language the current language code, null disables multilang support
+     * @param string $currentlanguage the current language code, null disables multilang support
      */
     public function __construct($definition = '', $currentlanguage = null) {
-
         $this->currentlanguage = $currentlanguage;
         parent::__construct('root'); // create virtual root element of the menu
         if (!empty($definition)) {
@@ -2436,6 +2638,8 @@ class custom_menu extends custom_menu_item {
     /**
      * Overrides the children of this custom menu. Useful when getting children
      * from $CFG->custommenuitems
+     *
+     * @param array $children
      */
     public function override_children(array $children) {
         $this->children = array();
@@ -2554,6 +2758,7 @@ class custom_menu extends custom_menu_item {
      * This function is designed to be used with the usort method
      *     usort($this->children, array('custom_menu','sort_custom_menu_items'));
      *
+     * @static
      * @param custom_menu_item $itema
      * @param custom_menu_item $itemb
      * @return int
@@ -2566,4 +2771,4 @@ class custom_menu extends custom_menu_item {
         }
         return ($itema > $itemb) ? +1 : -1;
     }
-}
+}
\ No newline at end of file
index 8e5a35b..cdfbf5e 100644 (file)
@@ -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
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
 /**
- * Interface and classes for creating appropriate renderers for various
- * parts of Moodle.
+ * Interface and classes for creating appropriate renderers for various parts of Moodle.
  *
  * Please see http://docs.moodle.org/en/Developement:How_Moodle_outputs_HTML
  * for an overview.
  *
- * @package    core
- * @subpackage lib
- * @copyright  2009 Tim Hunt
- * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @copyright 2009 Tim Hunt
+ * @license  http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @package core
+ * @category output
  */
 
 defined('MOODLE_INTERNAL') || die();
@@ -45,7 +43,7 @@ define('RENDERER_TARGET_TEXTEMAIL', 'textemail');
 /** Rich text html rendering intended for sending via email */
 define('RENDERER_TARGET_HTMLEMAIL', 'htmlemail');
 
-/* note: maybe we could define portfolio export target too */
+// note: maybe we could define portfolio export target too
 
 
 /**
@@ -59,10 +57,13 @@ define('RENDERER_TARGET_HTMLEMAIL', 'htmlemail');
  * (See {@link renderer_factory_base::__construct} for an example.)
  *
  * @copyright 2009 Tim Hunt
- * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since     Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
  */
 interface renderer_factory {
+
     /**
      * Return the renderer for a particular part of Moodle.
      *
@@ -86,7 +87,7 @@ interface renderer_factory {
      * @param string $component name such as 'core', 'mod_forum' or 'qtype_multichoice'.
      * @param string $subtype optional subtype such as 'news' resulting to 'mod_forum_news'
      * @param string $target one of rendering target constants
-     * @return object an object implementing the requested renderer interface.
+     * @return renderer_base an object implementing the requested renderer interface.
      */
     public function get_renderer(moodle_page $page, $component, $subtype=null, $target=null);
 }
@@ -102,15 +103,20 @@ interface renderer_factory {
  * the definition of, the standard renderer class for a given module.
  *
  * @copyright 2009 Tim Hunt
- * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since     Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
  */
 abstract class renderer_factory_base implements renderer_factory {
-    /** @var theme_config the theme we belong to. */
+    /**
+     * @var theme_config The theme we belong to.
+     */
     protected $theme;
 
     /**
      * Constructor.
+     *
      * @param theme_config $theme the theme we belong to.
      */
     public function __construct(theme_config $theme) {
@@ -119,6 +125,7 @@ abstract class renderer_factory_base implements renderer_factory {
 
     /**
      * Returns suffix of renderer class expected for given target.
+     *
      * @param string $target one of the renderer target constants, target is guessed if null used
      * @return array two element array, first element is target, second the target suffix string
      */
@@ -195,23 +202,27 @@ abstract class renderer_factory_base implements renderer_factory {
     }
 }
 
-
 /**
- * This is the default renderer factory for Moodle. It simply returns an instance
- * of the appropriate standard renderer class.
+ * This is the default renderer factory for Moodle.
+ *
+ * It simply returns an instance of the appropriate standard renderer class.
  *
  * @copyright 2009 Tim Hunt
- * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since     Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
  */
 class standard_renderer_factory extends renderer_factory_base {
+
     /**
      * Implement the subclass method
+     *
      * @param moodle_page $page the page the renderer is outputting content for.
      * @param string $component name such as 'core', 'mod_forum' or 'qtype_multichoice'.
      * @param string $subtype optional subtype such as 'news' resulting to 'mod_forum_news'
      * @param string $target one of rendering target constants
-     * @return object an object implementing the requested renderer interface.
+     * @return renderer_base an object implementing the requested renderer interface.
      */
     public function get_renderer(moodle_page $page, $component, $subtype = null, $target = null) {
         $classname = $this->standard_renderer_classname($component, $subtype);
@@ -232,8 +243,7 @@ class standard_renderer_factory extends renderer_factory_base {
 
 
 /**
- * This is renderer factory allows themes to override the standard renderers using
- * php code.
+ * This is renderer factory allows themes to override the standard renderers using php code.
  *
  * It will load any code from theme/mytheme/renderers.php and
  * theme/parenttheme/renderers.php, if then exist. Then whenever you ask for
@@ -242,16 +252,21 @@ class standard_renderer_factory extends renderer_factory_base {
  * if either of those classes exist.
  *
  * @copyright 2009 Tim Hunt
- * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since     Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
  */
 class theme_overridden_renderer_factory extends renderer_factory_base {
 
+    /**
+     * @var array An array of renderer prefixes
+     */
     protected $prefixes = array();
 
     /**
      * Constructor.
-     * @param object $theme the theme we are rendering for.
+     * @param theme_config $theme the theme we are rendering for.
      */
     public function __construct(theme_config $theme) {
         parent::__construct($theme);
@@ -261,11 +276,12 @@ class theme_overridden_renderer_factory extends renderer_factory_base {
 
     /**
      * Implement the subclass method
+     *
      * @param moodle_page $page the page the renderer is outputting content for.
      * @param string $component name such as 'core', 'mod_forum' or 'qtype_multichoice'.
      * @param string $subtype optional subtype such as 'news' resulting to 'mod_forum_news'
      * @param string $target one of rendering target constants
-     * @return object an object implementing the requested renderer interface.
+     * @return renderer_base an object implementing the requested renderer interface.
      */
     public function get_renderer(moodle_page $page, $component, $subtype = null, $target = null) {
         $classname = $this->standard_renderer_classname($component, $subtype);
@@ -303,4 +319,4 @@ class theme_overridden_renderer_factory extends renderer_factory_base {
 
         return new $classname($page, $target);
     }
-}
+}
\ No newline at end of file
index 8feae4c..9d53be7 100644 (file)
@@ -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
  * Please see http://docs.moodle.org/en/Developement:How_Moodle_outputs_HTML
  * for an overview.
  *
- * @package    core
- * @subpackage lib
- * @copyright  2009 Tim Hunt
- * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @copyright 2009 Tim Hunt
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @package core
+ * @category output
  */
 
 defined('MOODLE_INTERNAL') || die();
@@ -37,7 +36,11 @@ require_once($CFG->libdir.'/outputrequirementslib.php');
 
 /**
  * Invalidate all server and client side caches.
- * @return void
+ *
+ * This method deletes the phsyical directory that is used to cache the theme
+ * files used for serving.
+ * Because it deletes the main theme cache directoy all themes are reset by
+ * this function.
  */
 function theme_reset_all_caches() {
     global $CFG;
@@ -49,8 +52,8 @@ function theme_reset_all_caches() {
 
 /**
  * Enable or disable theme designer mode.
+ *
  * @param bool $state
- * @return void
  */
 function theme_set_designer_mod($state) {
     theme_reset_all_caches();
@@ -59,6 +62,7 @@ function theme_set_designer_mod($state) {
 
 /**
  * Returns current theme revision number.
+ *
  * @return int
  */
 function theme_get_revision() {
@@ -81,10 +85,10 @@ function theme_get_revision() {
  * This class represents the configuration variables of a Moodle theme.
  *
  * All the variables with access: public below (with a few exceptions that are marked)
- * are the properties you can set in your theme's config.php file.
+ * are the properties you can set in your themes config.php file.
  *
  * There are also some methods and protected variables that are part of the inner
- * workings of Moodle's themes system. If you are just editing a theme's config.php
+ * workings of Moodle's themes system. If you are just editing a themes config.php
  * file, you can just ignore those, and the following information for developers.
  *
  * Normally, to create an instance of this class, you should use the
@@ -93,87 +97,75 @@ function theme_get_revision() {
  * will create one for you, accessible as $PAGE->theme.
  *
  * @copyright 2009 Tim Hunt
- * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since     Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
  */
 class theme_config {
+
     /**
-     * @var string default theme, used when requested theme not found
+     * @var string Default theme, used when requested theme not found.
      */
     const DEFAULT_THEME = 'standard';
 
     /**
-     * You can base your theme on other themes by linking to the other theme as
+     * @var array You can base your theme on other themes by linking to the other theme as
      * parents. This lets you use the CSS and layouts from the other themes
-     * (see {@link $layouts}).
+     * (see {@link theme_config::$layouts}).
      * That makes it easy to create a new theme that is similar to another one
-     * but with a few changes. In this theme's CSS you only need to override
+     * but with a few changes. In this themes CSS you only need to override
      * those rules you want to change.
-     *
-     * @var array
      */
     public $parents;
 
     /**
-     * The names of all the stylesheets from this theme that you would
+     * @var array The names of all the stylesheets from this theme that you would
      * like included, in order. Give the names of the files without .css.
-     *
-     * @var array
      */
     public $sheets = array();
 
     /**
-     * The names of all the stylesheets from parents that should be excluded.
+     * @var array The names of all the stylesheets from parents that should be excluded.
      * true value may be used to specify all parents or all themes from one parent.
      * If no value specified value from parent theme used.
-     *
-     * @var array or arrays, true means all, null means use value from parent
      */
     public $parents_exclude_sheets = null;
 
     /**
-     * List of plugin sheets to be excluded.
+     * @var array List of plugin sheets to be excluded.
      * If no value specified value from parent theme used.
-     *
-     * @var array of full plugin names, null means use value from parent
      */
     public $plugins_exclude_sheets = null;
 
     /**
-     * List of style sheets that are included in the text editor bodies.
+     * @var array List of style sheets that are included in the text editor bodies.
      * Sheets from parent themes are used automatically and can not be excluded.
-     *
-     * @var array
      */
     public $editor_sheets = array();
 
     /**
-     * The names of all the javascript files this theme that you would
+     * @var array The names of all the javascript files this theme that you would
      * like included from head, in order. Give the names of the files without .js.
-     *
-     * @var array
      */
     public $javascripts = array();
 
     /**
-     * The names of all the javascript files this theme that you would
+     * @var array The names of all the javascript files this theme that you would
      * like included from footer, in order. Give the names of the files without .js.
-     *
-     * @var array
      */
     public $javascripts_footer = array();
 
     /**
-     * The names of all the javascript files from parents that should be excluded.
-     * true value may be used to specify all parents or all themes from one parent.
+     * @var array The names of all the javascript files from parents that should
+     * be excluded. true value may be used to specify all parents or all themes
+     * from one parent.
      * If no value specified value from parent theme used.
-     *
-     * @var array or arrays, true means all, null means use value from parent
      */
     public $parents_exclude_javascripts = null;
 
     /**
-     * Which file to use for each page layout.
+     * @var array Which file to use for each page layout.
      *
      * This is an array of arrays. The keys of the outer array are the different layouts.
      * Pages in Moodle are using several different layouts like 'normal', 'course', 'home',
@@ -219,13 +211,12 @@ class theme_config {
      * the page, but in non-existent regions, they appear here. (Imaging, for example,
      * that someone added blocks using a different theme that used different region
      * names, and then switched to this theme.)
-     *
-     * @var array
      */
     public $layouts = array();
 
     /**
-     * Name of the renderer factory class to use.
+     * @var string Name of the renderer factory class to use. Must implement the
+     * {@link renderer_factory} interface.
      *
      * This is an advanced feature. Moodle output is generated by 'renderers',
      * you can customise the HTML that is output by writing custom renderers,
@@ -239,99 +230,83 @@ class theme_config {
      * <li>{@link theme_overridden_renderer_factory} - use this if you want to write
      *      your own custom renderers in a lib.php file in this theme (or the parent theme).</li>
      * </ul>
-     *
-     * @var string name of a class implementing the {@link renderer_factory} interface.
      */
     public $rendererfactory = 'standard_renderer_factory';
 
     /**
-     * Function to do custom CSS post-processing.
+     * @var string Function to do custom CSS post-processing.
      *
      * This is an advanced feature. If you want to do custom post-processing on the
      * CSS before it is output (for example, to replace certain variable names
      * with particular values) you can give the name of a function here.
-     *
-     * @var string the name of a function.
      */
     public $csspostprocess = null;
 
     /**
-     * Accessibility: Right arrow-like character is
+     * @var string Accessibility: Right arrow-like character is
      * used in the breadcrumb trail, course navigation menu
      * (previous/next activity), calendar, and search forum block.
      * If the theme does not set characters, appropriate defaults
      * are set automatically. Please DO NOT
      * use &lt; &gt; &raquo; - these are confusing for blind users.
-     *
-     * @var string
      */
     public $rarrow = null;
 
     /**
-     * Accessibility: Right arrow-like character is
+     * @var string Accessibility: Right arrow-like character is
      * used in the breadcrumb trail, course navigation menu
      * (previous/next activity), calendar, and search forum block.
      * If the theme does not set characters, appropriate defaults
      * are set automatically. Please DO NOT
      * use &lt; &gt; &raquo; - these are confusing for blind users.
-     *
-     * @var string
      */
     public $larrow = null;
 
     /**
-     * Some themes may want to disable ajax course editing.
-     * @var bool
+     * @var bool Some themes may want to disable ajax course editing.
      */
     public $enablecourseajax = true;
 
     //==Following properties are not configurable from theme config.php==
 
     /**
-     * The name of this theme. Set automatically when this theme is
+     * @var string The name of this theme. Set automatically when this theme is
      * loaded. This can not be set in theme config.php
-     * @var string
      */
     public $name;
 
     /**
-     * the folder where this themes files are stored. This is set
+     * @var string The folder where this themes files are stored. This is set
      * automatically. This can not be set in theme config.php
-     * @var string
      */
     public $dir;
 
     /**
-     * Theme settings stored in config_plugins table.
+     * @var stdClass Theme settings stored in config_plugins table.
      * This can not be set in theme config.php
-     * @var object
      */
     public $setting = null;
 
     /**
-     * If set to true and the theme enables the dock then  blocks will be able
+     * @var bool If set to true and the theme enables the dock then  blocks will be able
      * to be moved to the special dock
-     * @var bool
      */
     public $enable_dock = false;
 
     /**
-     * If set to true then this theme will not be shown in the theme selector unless
+     * @var bool If set to true then this theme will not be shown in the theme selector unless
      * theme designer mode is turned on.
-     * @var bool
      */
     public $hidefromselector = false;
 
     /**
-     * Instance of the renderer_factory implementation
+     * @var renderer_factory Instance of the renderer_factory implementation
      * we are using. Implementation detail.
-     * @var renderer_factory
      */
     protected $rf = null;
 
     /**
-     * List of parent config objects.
-     * @var array list of parent configs
+     * @var array List of parent config objects.
      **/
     protected $parent_configs = array();
 
@@ -460,7 +435,7 @@ class theme_config {
         $this->check_theme_arrows();
     }
 
-    /*
+    /**
      * Checks if arrows $THEME->rarrow, $THEME->larrow have been set (theme/-/config.php).
      * If not it applies sensible defaults.
      *
@@ -498,7 +473,7 @@ class theme_config {
                 $this->larrow = '&lt;';
             }
 
-        /// RTL support - in RTL languages, swap r and l arrows
+            // RTL support - in RTL languages, swap r and l arrows
             if (right_to_left()) {
                 $t = $this->rarrow;
                 $this->rarrow = $this->larrow;
@@ -510,6 +485,7 @@ class theme_config {
     /**
      * Returns output renderer prefixes, these are used when looking
      * for the overridden renderers in themes.
+     *
      * @return array
      */
     public function renderer_prefixes() {
@@ -526,6 +502,7 @@ class theme_config {
 
     /**
      * Returns the stylesheet URL of this editor content
+     *
      * @param bool $encoded false means use & and true use &amp; in URLs
      * @return string
      */
@@ -545,6 +522,7 @@ class theme_config {
 
     /**
      * Returns the content of the CSS to be used in editor content
+     *
      * @return string
      */
     public function editor_css_files() {
@@ -587,7 +565,8 @@ class theme_config {
 
     /**
      * Get the stylesheet URL of this theme
-     * @param bool $encoded false means use & and true use &amp; in URLs
+     *
+     * @param moodle_page $page Not used... deprecated?
      * @return array of moodle_url
      */
     public function css_urls(moodle_page $page) {
@@ -664,6 +643,7 @@ class theme_config {
 
     /**
      * Returns an array of organised CSS files required for this output
+     *
      * @return array
      */
     public function css_files() {
@@ -732,6 +712,7 @@ class theme_config {
 
     /**
      * Returns the content of the one huge CSS merged from all style sheets.
+     *
      * @return string
      */
     public function css_content() {
@@ -744,7 +725,7 @@ class theme_config {
      * Given an array of file paths or a single file path loads the contents of
      * the CSS file, processes it then returns it in the same structure it was given.
      *
-     * Can be used recursively on the results of {@see css_files}
+     * Can be used recursively on the results of {@link css_files}
      *
      * @param array|string $file An array of file paths or a single file path
      * @param array $keys An array of previous array keys [recursive addition]
@@ -764,7 +745,8 @@ class theme_config {
 
 
     /**
-     * Get the javascript URL of this theme
+     * Generate a URL to the file that serves theme JavaScript files.
+     *
      * @param bool $inhead true means head url, false means footer
      * @return moodle_url
      */
@@ -778,6 +760,14 @@ class theme_config {
         return new moodle_url($CFG->httpswwwroot.'/theme/javascript.php', $params);
     }
 
+    /**
+     * Get the URL's for the JavaScript files used by this theme.
+     * They won't be served directly, instead they'll be mediated through
+     * theme/javascript.php.
+     *
+     * @param string $type Either javascripts_footer, or javascripts
+     * @return array
+     */
     public function javascript_files($type) {
         if ($type === 'footer') {
             $type = 'javascripts_footer';
@@ -824,13 +814,14 @@ class theme_config {
     }
 
     /**
-     * Resolves an exclude setting to the theme's setting is applicable or the
+     * Resolves an exclude setting to the themes setting is applicable or the
      * setting of its closest parent.
      *
      * @param string $variable The name of the setting the exclude setting to resolve
+     * @param string $default
      * @return mixed
      */
-    protected function resolve_excludes($variable, $default=null) {
+    protected function resolve_excludes($variable, $default = null) {
         $setting = $default;
         if (is_array($this->{$variable}) or $this->{$variable} === true) {
             $setting = $this->{$variable};
@@ -850,7 +841,8 @@ class theme_config {
 
     /**
      * Returns the content of the one huge javascript file merged from all theme javascript files.
-     * @param bool $inhead
+     *
+     * @param bool $type
      * @return string
      */
     public function javascript_content($type) {
@@ -862,6 +854,17 @@ class theme_config {
         return $js;
     }
 
+    /**
+     * Post processes CSS.
+     *
+     * This method post processes all of the CSS before it is served for this theme.
+     * This is done so that things such as image URL's can be swapped in and to
+     * run any specific CSS post process method the theme has requested.
+     * This allows themes to use CSS settings.
+     *
+     * @param string $css The CSS to process.
+     * @return string The processed CSS.
+     */
     public function post_process($css) {
         global $CFG;
 
@@ -895,7 +898,7 @@ class theme_config {
      * Return the URL for an image
      *
      * @param string $imagename the name of the icon.
-     * @param string $component, specification of one plugin like in get_string()
+     * @param string $component specification of one plugin like in get_string()
      * @return moodle_url
      */
     public function pix_url($imagename, $component) {
@@ -975,6 +978,7 @@ class theme_config {
 
     /**
      * Checks if file with any image extension exists.
+     *
      * @param string $filepath
      * @return string image name with extension
      */
@@ -994,9 +998,10 @@ class theme_config {
 
     /**
      * Loads the theme config from config.php file.
+     *
      * @param string $themename
-     * @param object $settings from config_plugins table
-     * @return object
+     * @param stdClass $settings from config_plugins table
+     * @return stdClass The theme configuration
      */
     private static function find_theme_config($themename, $settings) {
         // We have to use the variable name $THEME (upper case) because that
@@ -1026,6 +1031,7 @@ class theme_config {
     /**
      * Finds the theme location and verifies the theme has all needed files
      * and is not obsoleted.
+     *
      * @param string $themename
      * @return string full dir path or null if not found
      */
@@ -1052,8 +1058,9 @@ class theme_config {
 
     /**
      * Get the renderer for a part of Moodle for this theme.
+     *
      * @param moodle_page $page the page we are rendering
-     * @param string $module the name of part of moodle. E.g. 'core', 'quiz', 'qtype_multichoice'.
+     * @param string $component the name of part of moodle. E.g. 'core', 'quiz', 'qtype_multichoice'.
      * @param string $subtype optional subtype such as 'news' resulting to 'mod_forum_news'
      * @param string $target one of rendering target constants
      * @return renderer_base the requested renderer.
@@ -1069,6 +1076,7 @@ class theme_config {
 
     /**
      * Get the information from {@link $layouts} for this type of page.
+     *
      * @param string $pagelayout the the page layout name.
      * @return array the appropriate part of {@link $layouts}.
      */
@@ -1120,6 +1128,7 @@ class theme_config {
 
     /**
      * Returns auxiliary page layout options specified in layout configuration array.
+     *
      * @param string $pagelayout
      * @return array
      */
@@ -1134,9 +1143,9 @@ class theme_config {
     /**
      * Inform a block_manager about the block regions this theme wants on this
      * page layout.
+     *
      * @param string $pagelayout the general type of the page.
      * @param block_manager $blockmanager the block_manger to set up.
-     * @return void
      */
     public function setup_blocks($pagelayout, $blockmanager) {
         $layoutinfo = $this->layout_info_for_page($pagelayout);
@@ -1146,6 +1155,13 @@ class theme_config {
         }
     }
 
+    /**
+     * Gets the visible name for the requested block region.
+     *
+     * @param string $region The region name to get
+     * @param string $theme The theme the region belongs to (may come from the parent theme)
+     * @return string
+     */
     protected function get_region_name($region, $theme) {
         $regionstring = get_string('region-' . $region, 'theme_' . $theme);
         // A name exists in this theme, so use it
@@ -1168,6 +1184,7 @@ class theme_config {
 
     /**
      * Get the list of all block regions known to this theme in all templates.
+     *
      * @return array internal region name => human readable name.
      */
     public function get_all_block_regions() {
@@ -1190,7 +1207,6 @@ class theme_config {
     }
 }
 
-
 /**
  * This class keeps track of which HTML tags are currently open.
  *
@@ -1200,34 +1216,43 @@ class theme_config {
  * onto the stack.
  *
  * @copyright 2009 Tim Hunt
- * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since     Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
  */
 class xhtml_container_stack {
-    /** @var array stores the list of open containers. */
+
+    /**
+     * @var array Stores the list of open containers.
+     */
     protected $opencontainers = array();
+
     /**
-     * @var array in developer debug mode, stores a stack trace of all opens and
+     * @var array In developer debug mode, stores a stack trace of all opens and
      * closes, so we can output helpful error messages when there is a mismatch.
      */
     protected $log = array();
+
     /**
-     * Store whether we are developer debug mode. We need this in several places
-     * including in the destructor where we may not have access to $CFG.
-     * @var boolean
+     * @var boolean Store whether we are developer debug mode. We need this in
+     * several places including in the destructor where we may not have access to $CFG.
      */
     protected $isdebugging;
 
+    /**
+     * Constructor
+     */
     public function __construct() {
         $this->isdebugging = debugging('', DEBUG_DEVELOPER);
     }
 
     /**
      * Push the close HTML for a recently opened container onto the stack.
+     *
      * @param string $type The type of container. This is checked when {@link pop()}
      *      is called and must match, otherwise a developer debug warning is output.
      * @param string $closehtml The HTML required to close the container.
-     * @return void
      */
     public function push($type, $closehtml) {
         $container = new stdClass;
@@ -1243,6 +1268,7 @@ class xhtml_container_stack {
      * Pop the HTML for the next closing container from the stack. The $type
      * must match the type passed when the container was opened, otherwise a
      * warning will be output.
+     *
      * @param string $type The type of container.
      * @return string the HTML required to close the container.
      */
@@ -1270,6 +1296,7 @@ class xhtml_container_stack {
      * Close all but the last open container. This is useful in places like error
      * handling, where you want to close all the open containers (apart from <body>)
      * before outputting the error message.
+     *
      * @param bool $shouldbenone assert that the stack should be empty now - causes a
      *      developer debug warning if it isn't.
      * @return string the HTML required to close any open containers inside <body>.
@@ -1292,7 +1319,6 @@ class xhtml_container_stack {
      * class without properly emptying the stack (for example, in a unit test).
      * Calling this method stops the destruct method from outputting a developer
      * debug warning. After calling this method, the instance can no longer be used.
-     * @return void
      */
     public function discard() {
         $this->opencontainers = null;
@@ -1300,9 +1326,9 @@ class xhtml_container_stack {
 
     /**
      * Adds an entry to the log.
+     *
      * @param string $action The name of the action
      * @param string $type The type of action
-     * @return void
      */
     protected function log($action, $type) {
         $this->log[] = '<li>' . $action . ' ' . $type . ' at:' .
@@ -1311,9 +1337,10 @@ class xhtml_container_stack {
 
     /**
      * Outputs the log's contents as a HTML list.
+     *
      * @return string HTML list of the log
      */
     protected function output_log() {
         return '<ul>' . implode("\n", $this->log) . '</ul>';
     }
-}
+}
\ No newline at end of file
index b7e7574..52c1bab 100644 (file)
@@ -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
 /**
  * Classes for rendering HTML output for Moodle.
  *
- * Please see http://docs.moodle.org/en/Developement:How_Moodle_outputs_HTML
+ * Please see {@link http://docs.moodle.org/en/Developement:How_Moodle_outputs_HTML}
  * for an overview.
  *
- * @package    core
- * @subpackage lib
+ * Included in this file are the primary renderer classes:
+ *     - renderer_base:         The renderer outline class that all renderers
+ *                              should inherit from.
+ *     - core_renderer:         The standard HTML renderer.
+ *     - core_renderer_cli:     An adaption of the standard renderer for CLI scripts.
+ *     - core_renderer_ajax:    An adaption of the standard renderer for AJAX scripts.
+ *     - plugin_renderer_base:  A renderer class that should be extended by all
+ *                              plugin renderers.
+ *
+ * @package core
+ * @category output
  * @copyright  2009 Tim Hunt
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
@@ -37,19 +45,35 @@ defined('MOODLE_INTERNAL') || die();
  * Also has methods to facilitate generating HTML output.
  *
  * @copyright 2009 Tim Hunt
- * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since     Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
  */
 class renderer_base {
-    /** @var xhtml_container_stack the xhtml_container_stack to use. */
+    /**
+     * @var xhtml_container_stack The xhtml_container_stack to use.
+     */
     protected $opencontainers;
-    /** @var moodle_page the page we are rendering for. */
+
+    /**
+     * @var moodle_page The Moodle page the renderer has been created to assist with.
+     */
     protected $page;
-    /** @var requested rendering target */
+
+    /**
+     * @var string The requested rendering target.
+     */
     protected $target;
 
     /**
      * Constructor
+     *
+     * The constructor takes two arguments. The first is the page that the renderer
+     * has been created to assist with, and the second is the target.
+     * The target is an additional identifier that can be used to load different
+     * renderers for different options.
+     *
      * @param moodle_page $page the page we are doing output for.
      * @param string $target one of rendering target constants
      */
@@ -61,6 +85,13 @@ class renderer_base {
 
     /**
      * Returns rendered widget.
+     *
+     * The provided widget needs to be an object that extends the renderable
+     * interface.
+     * If will then be rendered by a method based upon the classname for the widget.
+     * For instance a widget of class `crazywidget` will be rendered by a protected
+     * render_crazywidget method of this renderer.
+     *
      * @param renderable $widget instance with renderable interface
      * @return string
      */
@@ -73,12 +104,17 @@ class renderer_base {
     }
 
     /**
-     * Adds JS handlers needed for event execution for one html element id
-     * @param component_action $actions
+     * Adds a JS action for the element with the provided id.
+     *
+     * This method adds a JS event for the provided component action to the page
+     * and then returns the id that the event has been attached to.
+     * If no id has been provided then a new ID is generated by {@link html_writer::random_id()}
+     *
+     * @param component_action $action
      * @param string $id
      * @return string id of element, either original submitted or random new if not supplied
      */
-    public function add_action_handler(component_action $action, $id=null) {
+    public function add_action_handler(component_action $action, $id = null) {
         if (!$id) {
             $id = html_writer::random_id($action->event);
         }
@@ -87,7 +123,8 @@ class renderer_base {
     }
 
     /**
-     * Have we started output yet?
+     * Returns true is output has already started, and false if not.
+     *
      * @return boolean true if the header has been printed.
      */
     public function has_started() {
@@ -96,6 +133,7 @@ class renderer_base {
 
     /**
      * Given an array or space-separated list of classes, prepares and returns the HTML class attribute value
+     *
      * @param mixed $classes Space-separated string or array of classes
      * @return string HTML class attribute value
      */
@@ -108,6 +146,7 @@ class renderer_base {
 
     /**
      * Return the moodle_url for an image.
+     *
      * The exact image location and extension is determined
      * automatically by searching for gif|png|jpg|jpeg, please
      * note there can not be diferent images with the different
@@ -138,19 +177,24 @@ class renderer_base {
 /**
  * Basis for all plugin renderers.
  *
- * @author    Petr Skoda (skodak)
- * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since     Moodle 2.0
+ * @copyright Petr Skoda (skodak)
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
  */
 class plugin_renderer_base extends renderer_base {
+
     /**
-     * A reference to the current general renderer probably {@see core_renderer}
-     * @var renderer_base
+     * @var renderer_base|core_renderer A reference to the current renderer.
+     * The renderer provided here will be determined by the page but will in 90%
+     * of cases by the {@link core_renderer}
      */
     protected $output;
 
     /**
      * Constructor method, calls the parent constructor
+     *
      * @param moodle_page $page
      * @param string $target one of rendering target constants
      */
@@ -160,7 +204,8 @@ class plugin_renderer_base extends renderer_base {
     }
 
     /**
-     * Returns rendered widget.
+     * Renders the provided widget and returns the HTML to display it.
+     *
      * @param renderable $widget instance with renderable interface
      * @return string
      */
@@ -198,30 +243,50 @@ class plugin_renderer_base extends renderer_base {
  * The standard implementation of the core_renderer interface.
  *
  * @copyright 2009 Tim Hunt
- * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since     Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
  */
 class core_renderer extends renderer_base {
     /**
      * Do NOT use, please use <?php echo $OUTPUT->main_content() ?>
      * in layout files instead.
-     * @var string used in {@link header()}.
      * @deprecated
+     * @var string used in {@link core_renderer::header()}.
      */
     const MAIN_CONTENT_TOKEN = '[MAIN CONTENT GOES HERE]';
-    /** @var string used to pass information from {@link doctype()} to {@link standard_head_html()}. */
+
+    /**
+     * @var string Used to pass information from {@link core_renderer::doctype()} to
+     * {@link core_renderer::standard_head_html()}.
+     */
     protected $contenttype;
-    /** @var string used by {@link redirect_message()} method to communicate with {@link header()}. */
+
+    /**
+     * @var string Used by {@link core_renderer::redirect_message()} method to communicate
+     * with {@link core_renderer::header()}.
+     */
     protected $metarefreshtag = '';
-    /** @var string unique token */
+
+    /**
+     * @var string Unique token for the closing HTML
+     */
     protected $unique_end_html_token;
-    /** @var string unique token */
+
+    /**
+     * @var string Unique token for performance information
+     */
     protected $unique_performance_info_token;
-    /** @var string unique token */
+
+    /**
+     * @var string Unique token for the main content.
+     */
     protected $unique_main_content_token;
 
     /**
      * Constructor
+     *
      * @param moodle_page $page the page we are doing output for.
      * @param string $target one of rendering target constants
      */
@@ -238,6 +303,7 @@ class core_renderer extends renderer_base {
     /**
      * Get the DOCTYPE declaration that should be used with this page. Designed to
      * be called in theme layout.php files.
+     *
      * @return string the DOCTYPE declaration (and any XML prologue) that should be used.
      */
     public function doctype() {
@@ -271,6 +337,7 @@ class core_renderer extends renderer_base {
     /**
      * The attributes that should be added to the <html> tag. Designed to
      * be called in theme layout.php files.
+     *
      * @return string HTML fragment.
      */
     public function htmlattributes() {
@@ -281,6 +348,7 @@ class core_renderer extends renderer_base {
      * The standard tags (meta tags, links to stylesheets and JavaScript, etc.)
      * that should be included in the <head> tag. Designed to be called in theme
      * layout.php files.
+     *
      * @return string HTML fragment.
      */
     public function standard_head_html() {
@@ -354,6 +422,7 @@ class core_renderer extends renderer_base {
     /**
      * The standard tags (typically skip links) that should be output just inside
      * the start of the <body> tag. Designed to be called in theme layout.php files.
+     *
      * @return string HTML fragment.
      */
     public function standard_top_of_body_html() {
@@ -369,14 +438,15 @@ class core_renderer extends renderer_base {
      * The standard tags (typically performance information and validation links,
      * if we are in developer debug mode) that should be output in the footer area
      * of the page. Designed to be called in theme layout.php files.
+     *
      * @return string HTML fragment.
      */
     public function standard_footer_html() {
         global $CFG, $SCRIPT;
 
-        // This function is normally called from a layout.php file in {@link header()}
+        // This function is normally called from a layout.php file in {@link core_renderer::header()}
         // but some of the content won't be known until later, so we return a placeholder
-        // for now. This will be replaced with the real content in {@link footer()}.
+        // for now. This will be replaced with the real content in {@link core_renderer::footer()}.
         $output = $this->unique_performance_info_token;
         if ($this->page->devicetypeinuse == 'legacy') {
             // The legacy theme is in use print the notification
@@ -416,6 +486,7 @@ class core_renderer extends renderer_base {
     /**
      * Returns standard main content placeholder.
      * Designed to be called in theme layout.php files.
+     *
      * @return string HTML fragment.
      */
     public function main_content() {
@@ -425,18 +496,20 @@ class core_renderer extends renderer_base {
     /**
      * The standard tags (typically script tags that are not needed earlier) that
      * should be output after everything else, . Designed to be called in theme layout.php files.
+     *
      * @return string HTML fragment.
      */
     public function standard_end_of_body_html() {
-        // This function is normally called from a layout.php file in {@link header()}
+        // This function is normally called from a layout.php file in {@link core_renderer::header()}
         // but some of the content won't be known until later, so we return a placeholder
-        // for now. This will be replaced with the real content in {@link footer()}.
+        // for now. This will be replaced with the real content in {@link core_renderer::footer()}.
         return $this->unique_end_html_token;
     }
 
     /**
      * Return the standard string that says whether you are logged in (and switched
      * roles/logged in as another user).
+     *
      * @return string HTML fragment.
      */
     public function login_info() {
@@ -522,6 +595,7 @@ class core_renderer extends renderer_base {
 
     /**
      * Return the 'back' link that normally appears in the footer.
+     *
      * @return string HTML fragment.
      */
     public function home_link() {
@@ -666,6 +740,11 @@ class core_renderer extends renderer_base {
 
     /**
      * Renders and outputs the page layout file.
+     *
+     * This is done by preparing the normal globals available to a script, and
+     * then including the layout file provided by the current theme for the
+     * requested layout.
+     *
      * @param string $layoutfile The name of the layout file
      * @return string HTML code
      */
@@ -690,6 +769,7 @@ class core_renderer extends renderer_base {
 
     /**
      * Outputs the page's footer
+     *
      * @return string HTML fragment
      */
     public function footer() {
@@ -727,6 +807,7 @@ class core_renderer extends renderer_base {
      * Close all but the last open container. This is useful in places like error
      * handling, where you want to close all the open containers (apart from <body>)
      * before outputting the error message.
+     *
      * @param bool $shouldbenone assert that the stack should be empty now - causes a
      *      developer debug warning if it isn't.
      * @return string the HTML required to close any open containers inside <body>.
@@ -737,7 +818,8 @@ class core_renderer extends renderer_base {
 
     /**
      * Returns lang menu or '', this method also checks forcing of languages in courses.
-     * @return string
+     *
+     * @return string The lang menu HTML or empty string
      */
     public function lang_menu() {
         global $CFG;
@@ -766,8 +848,9 @@ class core_renderer extends renderer_base {
 
     /**
      * Output the row of editing icons for a block, as defined by the controls array.
+     *
      * @param array $controls an array like {@link block_contents::$controls}.
-     * @return HTML fragment.
+     * @return string HTML fragment.
      */
     public function block_controls($controls) {
         if (empty($controls)) {
@@ -786,7 +869,7 @@ class core_renderer extends renderer_base {
      * Prints a nice side block with an optional header.
      *
      * The content is described
-     * by a {@link block_contents} object.
+     * by a {@link core_renderer::block_contents} object.
      *
      * <div id="inst{$instanceid}" class="block_{$blockname} block">
      *      <div class="header"></div>
@@ -803,7 +886,7 @@ class core_renderer extends renderer_base {
      * @param string $region the region the block is appearing in.
      * @return string the HTML to be output.
      */
-    function block(block_contents $bc, $region) {
+    public function block(block_contents $bc, $region) {
         $bc = clone($bc); // Avoid messing up the object passed in.
         if (empty($bc->blockinstanceid) || !strip_tags($bc->title)) {
             $bc->collapsible = block_contents::NOT_HIDEABLE;
@@ -909,8 +992,8 @@ class core_renderer extends renderer_base {
 
     /**
      * Calls the JS require function to hide a block.
+     *
      * @param block_contents $bc A block_contents object
-     * @return void
      */
     protected function init_block_hider_js(block_contents $bc) {
         if (!empty($bc->attributes['id']) and $bc->collapsible != block_contents::NOT_HIDEABLE) {
@@ -928,6 +1011,7 @@ class core_renderer extends renderer_base {
 
     /**
      * Render the contents of a block_list.
+     *
      * @param array $icons the icon for each item.
      * @param array $items the content of each item.
      * @return string HTML
@@ -950,6 +1034,7 @@ class core_renderer extends renderer_base {
 
     /**
      * Output all the blocks in a particular region.
+     *
      * @param string $region the name of a region on this page.
      * @return string the HTML to be output.
      */
@@ -971,6 +1056,7 @@ class core_renderer extends renderer_base {
 
     /**
      * Output a place where the block that is currently being moved can be dropped.
+     *
      * @param block_move_target $target with the necessary details.
      * @return string the HTML to be output.
      */
@@ -985,7 +1071,7 @@ class core_renderer extends renderer_base {
      * @param string $text HTML fragment
      * @param component_action $action
      * @param array $attributes associative array of html link attributes + disabled
-     * @return HTML fragment
+     * @return string HTML fragment
      */
     public function action_link($url, $text, component_action $action = null, array $attributes=null) {
         if (!($url instanceof moodle_url)) {
@@ -997,7 +1083,11 @@ class core_renderer extends renderer_base {
     }
 
     /**
-     * Implementation of action_link rendering
+     * Renders an action_link object.
+     *
+     * The provided link is renderer and the HTML returned. At the same time the
+     * associated actions are setup in JS by {@link core_renderer::add_action_handler()}
+     *
      * @param action_link $link
      * @return string HTML fragment
      */
@@ -1037,7 +1127,11 @@ class core_renderer extends renderer_base {
 
 
     /**
-     * Similar to action_link, image is used instead of the text
+     * Renders an action_icon.
+     *
+     * This function uses the {@link core_renderer::action_link()} method for the
+     * most part. What it does different is prepare the icon as HTML and use it
+     * as the link text.
      *
      * @param string|moodle_url $url A string URL or moodel_url
      * @param pix_icon $pixicon
@@ -1131,7 +1225,10 @@ class core_renderer extends renderer_base {
     }
 
     /**
-     * Internal implementation of single_button rendering
+     * Renders a single button widget.
+     *
+     * This will return HTML to display a form containing a single button.
+     *
      * @param single_button $button
      * @return string HTML fragment
      */
@@ -1184,6 +1281,7 @@ class core_renderer extends renderer_base {
 
     /**
      * Returns a form with a single select widget.
+     *
      * @param moodle_url $url form action target, includes hidden fields
      * @param string $name name of selection field - the changing parameter in url
      * @param array $options list of options
@@ -1192,7 +1290,7 @@ class core_renderer extends renderer_base {
      * @param string $formid
      * @return string HTML fragment
      */
-    public function single_select($url, $name, array $options, $selected='', $nothing=array(''=>'choosedots'), $formid=null) {
+    public function single_select($url, $name, array $options, $selected = '', $nothing = array('' => 'choosedots'), $formid = null) {
         if (!($url instanceof moodle_url)) {
             $url = new moodle_url($url);
         }
@@ -1203,6 +1301,7 @@ class core_renderer extends renderer_base {
 
     /**
      * Internal implementation of single_select rendering
+     *
      * @param single_select $select
      * @return string HTML fragment
      */
@@ -1271,20 +1370,22 @@ class core_renderer extends renderer_base {
 
     /**
      * Returns a form with a url select widget.
+     *
      * @param array $urls list of urls - array('/course/view.php?id=1'=>'Frontpage', ....)
      * @param string $selected selected element
      * @param array $nothing
      * @param string $formid
      * @return string HTML fragment
      */
-    public function url_select(array $urls, $selected, $nothing=array(''=>'choosedots'), $formid=null) {
+    public function url_select(array $urls, $selected, $nothing = array('' => 'choosedots'), $formid = null) {
         $select = new url_select($urls, $selected, $nothing, $formid);
         return $this->render($select);
     }
 
     /**
      * Internal implementation of url_select rendering
-     * @param single_select $select
+     *
+     * @param url_select $select
      * @return string HTML fragment
      */
     protected function render_url_select(url_select $select) {
@@ -1391,6 +1492,7 @@ class core_renderer extends renderer_base {
     /**
      * Returns a string containing a link to the user documentation.
      * Also contains an icon by default. Shown to teachers and admin only.
+     *
      * @param string $path The page link after doc root and language, no leading slash.
      * @param string $text The text to be displayed for the link
      * @return string
@@ -1411,7 +1513,8 @@ class core_renderer extends renderer_base {
     }
 
     /**
-     * Render icon
+     * Return HTML for a pix_icon.
+     *
      * @param string $pix short pix name
      * @param string $alt mandatory alt attribute
      * @param string $component standard compoennt name like 'moodle', 'mod_forum', etc.
@@ -1424,7 +1527,8 @@ class core_renderer extends renderer_base {
     }
 
     /**
-     * Render icon
+     * Renders a pix_icon widget and returns the HTML to display it.
+     *
      * @param pix_icon $icon
      * @return string HTML fragment
      */
@@ -1435,7 +1539,8 @@ class core_renderer extends renderer_base {
     }
 
     /**
-     * Render emoticon
+     * Return HTML to display an emoticon icon.
+     *
      * @param pix_emoticon $emoticon
      * @return string HTML fragment
      */
@@ -1446,9 +1551,11 @@ class core_renderer extends renderer_base {
     }
 
     /**
-    * Produces the html that represents this rating in the UI
-    * @param $page the page object on which this rating will appear
-    */
+     * Produces the html that represents this rating in the UI
+     *
+     * @param rating $rating the page object on which this rating will appear
+     * @return string
+     */
     function render_rating(rating $rating) {
         global $CFG, $USER;
 
@@ -1540,9 +1647,10 @@ class core_renderer extends renderer_base {
         return $ratinghtml;
     }
 
-    /*
+    /**
      * Centered heading with attached help button (same title text)
-     * and optional icon attached
+     * and optional icon attached.
+     *
      * @param string $text A heading text
      * @param string $helpidentifier The keyword that defines a help page
      * @param string $component component name
@@ -1550,7 +1658,7 @@ class core_renderer extends renderer_base {
      * @param string $iconalt icon alt text
      * @return string HTML fragment
      */
-    public function heading_with_help($text, $helpidentifier, $component='moodle', $icon='', $iconalt='') {
+    public function heading_with_help($text, $helpidentifier, $component = 'moodle', $icon = '', $iconalt = '') {
         $image = '';
         if ($icon) {
             $image = $this->pix_icon($icon, $iconalt, $component, array('class'=>'icon'));
@@ -1565,10 +1673,10 @@ class core_renderer extends renderer_base {
     }
 
     /**
-     * Print a help icon.
+     * Returns HTML to display a help icon.
      *
      * @deprecated since Moodle 2.0
-     * @param string $page The keyword that defines a help page
+     * @param string $helpidentifier The keyword that defines a help page
      * @param string $title A descriptive text for accessibility only
      * @param string $component component name
      * @param string|bool $linktext true means use $title as link text, string means link text value
@@ -1587,7 +1695,8 @@ class core_renderer extends renderer_base {
 
     /**
      * Implementation of user image rendering.
-     * @param help_icon $helpicon
+     *
+     * @param old_help_icon $helpicon A help icon instance
      * @return string HTML fragment
      */
     protected function render_old_help_icon(old_help_icon $helpicon) {
@@ -1629,7 +1738,7 @@ class core_renderer extends renderer_base {
     }
 
     /**
-     * Print a help icon.
+     * Returns HTML to display a help icon.
      *
      * @param string $identifier The keyword that defines a help page
      * @param string $component component name
@@ -1649,7 +1758,8 @@ class core_renderer extends renderer_base {
 
     /**
      * Implementation of user image rendering.
-     * @param help_icon $helpicon
+     *
+     * @param help_icon $helpicon A help icon instance
      * @return string HTML fragment
      */
     protected function render_help_icon(help_icon $helpicon) {
@@ -1693,11 +1803,11 @@ class core_renderer extends renderer_base {
     }
 
     /**
-     * Print scale help icon.
+     * Returns HTML to display a scale help icon.
      *
      * @param int $courseid
-     * @param object $scale instance
-     * @return string  HTML fragment
+     * @param stdClass $scale instance
+     * @return string HTML fragment
      */
     public function help_icon_scale($courseid, stdClass $scale) {
         global $CFG;
@@ -1717,8 +1827,9 @@ class core_renderer extends renderer_base {
     /**
      * Creates and returns a spacer image with optional line break.
      *
-     * @param array $attributes
-     * @param boo spacer
+     * @param array $attributes Any HTML attributes to add to the spaced.
+     * @param bool $br Include a BR after the spacer.... DON'T USE THIS. Don't be
+     *     laxy do it with CSS which is a much better solution.
      * @return string HTML fragment
      */
     public function spacer(array $attributes = null, $br = false) {
@@ -1741,7 +1852,7 @@ class core_renderer extends renderer_base {
     }
 
     /**
-     * Print the specified user's avatar.
+     * Returns HTML to display the specified user's avatar.
      *
      * User avatar may be obtained in two ways:
      * <pre>
@@ -1756,7 +1867,7 @@ class core_renderer extends renderer_base {
      * $OUTPUT->render($userpic);
      * </pre>
      *
-     * @param object Object with at least fields id, picture, imagealt, firstname, lastname
+     * @param stdClass $user Object with at least fields id, picture, imagealt, firstname, lastname
      *     If any of these are missing, the database is queried. Avoid this
      *     if at all possible, particularly for reports. It is very bad for performance.
      * @param array $options associative array with user picture options, used only if not a user_picture object,
@@ -1781,6 +1892,7 @@ class core_renderer extends renderer_base {
 
     /**
      * Internal implementation of user image rendering.
+     *
      * @param user_picture $userpicture
      * @return string
      */
@@ -1850,6 +1962,7 @@ class core_renderer extends renderer_base {
 
     /**
      * Internal implementation of file tree viewer items rendering.
+     *
      * @param array $dir
      * @return string
      */
@@ -1869,8 +1982,9 @@ class core_renderer extends renderer_base {
 
         return $result;
     }
+
     /**
-     * Print the file picker
+     * Returns HTML to display the file picker
      *
      * <pre>
      * $OUTPUT->file_picker($options);
@@ -1890,8 +2004,10 @@ class core_renderer extends renderer_base {
         $fp = new file_picker($options);
         return $this->render($fp);
     }
+
     /**
      * Internal implementation of file picker rendering.
+     *
      * @param file_picker $fp
      * @return string
      */
@@ -1946,7 +2062,7 @@ EOD;
     }
 
     /**
-     * Prints the 'Update this Modulename' button that appears on module pages.
+     * Returns HTML to display the 'Update this Modulename' button that appears on module pages.
      *
      * @param string $cmid the course_module id.
      * @param string $modulename the module name, eg. "forum", "quiz" or "workshop"
@@ -1965,7 +2081,8 @@ EOD;
     }
 
     /**
-     * Prints a "Turn editing on/off" button in a form.
+     * Returns HTML to display a "Turn editing on/off" button in a form.
+     *
      * @param moodle_url $url The URL + params to send through when clicking the button
      * @return string HTML the button
      */
@@ -1984,7 +2101,7 @@ EOD;
     }
 
     /**
-     * Prints a simple button to close a window
+     * Returns HTML to display a simple button to close a window
      *
      * @param string $text The lang string for the button's label (already output from get_string())
      * @return string html fragment
@@ -2002,6 +2119,7 @@ EOD;
     /**
      * Output an error message. By default wraps the error message in <span class="error">.
      * If the error message is blank, nothing is output.
+     *
      * @param string $message the error message.
      * @return string the HTML to output.
      */
@@ -2115,7 +2233,7 @@ EOD;
     }
 
     /**
-     * Print a continue button that goes to a particular URL.
+     * Returns HTML to display a continue button that goes to a particular URL.
      *
      * @param string|moodle_url $url The url the button goes to.
      * @return string the HTML to output.
@@ -2131,7 +2249,7 @@ EOD;
     }
 
     /**
-     * Prints a single paging bar to provide access to other pages  (usually in a search)
+     * Returns HTML to display a single paging bar to provide access to other pages  (usually in a search)
      *
      * @param int $totalcount The total number of entries available to be paged through
      * @param int $page The page you are currently viewing
@@ -2147,6 +2265,7 @@ EOD;
 
     /**
      * Internal implementation of paging bar rendering.
+     *
      * @param paging_bar $pagingbar
      * @return string
      */
@@ -2184,6 +2303,7 @@ EOD;
 
     /**
      * Output the place a skip link goes to.
+     *
      * @param string $id The target name from the corresponding $PAGE->requires->skip_link_to($target) call.
      * @return string the HTML to output.
      */
@@ -2193,6 +2313,7 @@ EOD;
 
     /**
      * Outputs a heading
+     *
      * @param string $text The text of the heading
      * @param int $level The level of importance of the heading. Defaulting to 2
      * @param string $classes A space-separated list of CSS classes
@@ -2209,6 +2330,7 @@ EOD;
 
     /**
      * Outputs a box.
+     *
      * @param string $contents The contents of the box
      * @param string $classes A space-separated list of CSS classes
      * @param string $id An optional ID
@@ -2220,6 +2342,7 @@ EOD;
 
     /**
      * Outputs the opening section of a box.
+     *
      * @param string $classes A space-separated list of CSS classes
      * @param string $id An optional ID
      * @return string the HTML to output.
@@ -2232,6 +2355,7 @@ EOD;
 
     /**
      * Outputs the closing section of a box.
+     *
      * @return string the HTML to output.
      */
     public function box_end() {
@@ -2240,6 +2364,7 @@ EOD;
 
     /**
      * Outputs a container.
+     *
      * @param string $contents The contents of the box
      * @param string $classes A space-separated list of CSS classes
      * @param string $id An optional ID
@@ -2251,6 +2376,7 @@ EOD;
 
     /**
      * Outputs the opening section of a container.
+     *
      * @param string $classes A space-separated list of CSS classes
      * @param string $id An optional ID
      * @return string the HTML to output.
@@ -2263,6 +2389,7 @@ EOD;
 
     /**
      * Outputs the closing section of a container.
+     *
      * @return string the HTML to output.
      */
     public function container_end() {
@@ -2284,12 +2411,11 @@ EOD;
      * <</ul>>
      * </pre>
      *
-     * @param array[]tree_item $items
-     * @param array[string]string $attrs html attributes passed to the top of
-     * the list
+     * @param array $items
+     * @param array $attrs html attributes passed to the top ofs the list
      * @return string HTML
      */
-    function tree_block_contents($items, $attrs=array()) {
+    public function tree_block_contents($items, $attrs = array()) {
         // exit if empty, we don't want an empty ul element
         if (empty($items)) {
             return '';
@@ -2333,6 +2459,7 @@ EOD;
 
     /**
      * Return the navbar content so that it can be echoed out by the layout
+     *
      * @return string XHTML navbar
      */
     public function navbar() {
@@ -2360,6 +2487,12 @@ EOD;
         return $navbarcontent;
     }
 
+    /**
+     * Renders a navigation node object.
+     *
+     * @param navigation_node $item The navigation node to render.
+     * @return string HTML fragment
+     */
     protected function render_navigation_node(navigation_node $item) {
         $content = $item->get_content();
         $title = $item->get_title();
@@ -2410,6 +2543,7 @@ EOD;
      * If the theme does not set characters, appropriate defaults
      * are set automatically. Please DO NOT
      * use &lt; &gt; &raquo; - these are confusing for blind users.
+     *
      * @return string
      */
     public function rarrow() {
@@ -2423,6 +2557,7 @@ EOD;
      * If the theme does not set characters, appropriate defaults
      * are set automatically. Please DO NOT
      * use &lt; &gt; &raquo; - these are confusing for blind users.
+     *
      * @return string
      */
     public function larrow() {
@@ -2496,7 +2631,7 @@ EOD;
      * The custom menu this method produces makes use of the YUI3 menunav widget
      * and requires very specific html elements and classes.
      *
-     * @see render_custom_menu()
+     * @see core:renderer::render_custom_menu()
      *
      * @staticvar int $submenucount
      * @param custom_menu_item $menunode
@@ -2574,20 +2709,22 @@ EOD;
     }
 }
 
-/// RENDERERS
-
 /**
  * A renderer that generates output for command-line scripts.
  *
  * The implementation of this renderer is probably incomplete.
  *
  * @copyright 2009 Tim Hunt
- * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since     Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
  */
 class core_renderer_cli extends core_renderer {
+
     /**
      * Returns the page header.
+     *
      * @return string HTML fragment
      */
     public function header() {
@@ -2596,6 +2733,7 @@ class core_renderer_cli extends core_renderer {
 
     /**
      * Returns a template fragment representing a Heading.
+     *
      * @param string $text The text of the heading
      * @param int $level The level of importance of the heading
      * @param string $classes A space-separated list of CSS classes
@@ -2616,6 +2754,7 @@ class core_renderer_cli extends core_renderer {
 
     /**
      * Returns a template fragment representing a fatal error.
+     *
      * @param string $message The message to output
      * @param string $moreinfourl URL where more info can be found about the error
      * @param string $link Link for the Continue button
@@ -2640,6 +2779,7 @@ class core_renderer_cli extends core_renderer {
 
     /**
      * Returns a template fragment representing a notification.
+     *
      * @param string $message The message to include
      * @param string $classes A space-separated list of CSS classes
      * @return string A template fragment for a notification
@@ -2661,12 +2801,16 @@ class core_renderer_cli extends core_renderer {
  * encoded error messages, all other output is ignored.
  *
  * @copyright 2010 Petr Skoda
- * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @since     Moodle 2.0
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @since Moodle 2.0
+ * @package core
+ * @category output
  */
 class core_renderer_ajax extends core_renderer {
+
     /**
      * Returns a template fragment representing a fatal error.
+     *
      * @param string $message The message to output
      * @param string $moreinfourl URL where more info can be found about the error
      * @param string $link Link for the Continue button
@@ -2697,12 +2841,30 @@ class core_renderer_ajax extends core_renderer {
         return json_encode($e);
     }
 
-    public function notification($message, $classes = 'notifyproblem') {
-    }
+    /**
+     * Used to display a notification.
+     * For the AJAX notifications are discarded.
+     *
+     * @param string $message
+     * @param string $classes
+     */
+    public function notification($message, $classes = 'notifyproblem') {}
 
-    public function redirect_message($encodedurl, $message, $delay, $debugdisableredirect) {
-    }
+    /**
+     * Used to display a redirection message.
+     * AJAX redirections should not occur and as such redirection messages
+     * are discarded.
+     *
+     * @param moodle_url|string $encodedurl
+     * @param string $message
+     * @param int $delay
+     * @param bool $debugdisableredirect
+     */
+    public function redirect_message($encodedurl, $message, $delay, $debugdisableredirect) {}
 
+    /**
+     * Prepares the start of an AJAX output.
+     */
     public function header() {
         // unfortunately YUI iframe upload does not support application/json
         if (!empty($_FILES)) {
@@ -2711,7 +2873,7 @@ class core_renderer_ajax extends core_renderer {
             @header('Content-type: application/json; charset=utf-8');
         }
 
-        /// Headers to make it not cacheable and json
+        // Headers to make it not cacheable and json
         @header('Cache-Control: no-store, no-cache, must-revalidate');
         @header('Cache-Control: post-check=0, pre-check=0', false);
         @header('Pragma: no-cache');
@@ -2720,10 +2882,18 @@ class core_renderer_ajax extends core_renderer {
         @header('Accept-Ranges: none');
     }
 
-    public function footer() {
-    }
-
-    public function heading($text, $level = 2, $classes = 'main', $id = null) {
-    }
-}
+    /**
+     * There is no footer for an AJAX request, however we must override the
+     * footer method to prevent the default footer.
+     */
+    public function footer() {}
 
+    /**
+     * No need for headers in an AJAX request... this should never happen.
+     * @param string $text
+     * @param int $level
+     * @param string $classes
+     * @param string $id
+     */
+    public function heading($text, $level = 2, $classes = 'main', $id = null) {}
+}
\ No newline at end of file
index 2737fe5..52dc0b2 100644 (file)
@@ -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
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
-
 /**
  * Library functions to facilitate the use of JavaScript in Moodle.
  *
- * @package    core
- * @subpackage lib
- * @copyright  2009 Tim Hunt, 2010 Petr Skoda
- * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * Note: you can find history of this file in lib/ajax/ajaxlib.php
+ *
+ * @copyright 2009 Tim Hunt, 2010 Petr Skoda
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @package core
+ * @category output
  */
 
 defined('MOODLE_INTERNAL') || die();
 
-// note: you can find history of this file in lib/ajax/ajaxlib.php
-
 /**
  * This class tracks all the things that are needed by the current page.
  *
@@ -53,63 +51,99 @@ defined('MOODLE_INTERNAL') || die();
  * individual methods for details.
  *
  * @copyright 2009 Tim Hunt, 2010 Petr Skoda
- * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  * @since Moodle 2.0
+ * @package core
+ * @category output
  */
 class page_requirements_manager {
-    /** List of string available from JS */
+
+    /**
+     * @var array List of string available from JS
+     */
     protected $stringsforjs = array();
-    /** List of JS variables to be initialised */
+
+    /**
+     * @var array List of JS variables to be initialised
+     */
     protected $jsinitvariables = array('head'=>array(), 'footer'=>array());
-    /** Included JS scripts */
+
+    /**
+     * @var array Included JS scripts
+     */
     protected $jsincludes = array('head'=>array(), 'footer'=>array());
-    /** List of needed function calls */
+
+    /**
+     * @var array List of needed function calls
+     */
     protected $jscalls = array('normal'=>array(), 'ondomready'=>array());
+
     /**
-     * List of skip links, those are needed for accessibility reasons
-     * @var array
+     * @var array List of skip links, those are needed for accessibility reasons
      */
     protected $skiplinks = array();
+
     /**
-     * Javascript code used for initialisation of page, it should be relatively small
-     * @var array
+     * @var array Javascript code used for initialisation of page, it should
+     * be relatively small
      */
     protected $jsinitcode = array();
+
     /**
-     * Theme sheets, initialised only from core_renderer
-     * @var array of moodle_url
+     * @var array of moodle_url Theme sheets, initialised only from core_renderer
      */
     protected $cssthemeurls = array();
+
     /**
-     * List of custom theme sheets, these are strongly discouraged!
+     * @var array of moodle_url List of custom theme sheets, these are strongly discouraged!
      * Useful mostly only for CSS submitted by teachers that is not part of the theme.
-     * @var array of moodle_url
      */
     protected $cssurls = array();
+
     /**
-     * List of requested event handlers
-     * @var array
+     * @var array List of requested event handlers
      */
     protected $eventhandlers = array();
+
     /**
-     * Extra modules
-     * @var array
+     * @var array Extra modules
      */
     protected $extramodules = array();
-    /** Flag indicated head stuff already printed */
+
+    /**
+     * @var bool Flag indicated head stuff already printed
+     */
     protected $headdone = false;
-    /** Flag indicating top of body already printed */
+
+    /**
+     * @var bool Flag indicating top of body already printed
+     */
     protected $topofbodydone = false;
 
-    /** YUI PHPLoader instance responsible for YUI2 loading from PHP only */
+    /**
+     * @var YAHOO_util_Loader YUI PHPLoader instance responsible for YUI2 loading
+     * from PHP only
+     */
     protected $yui2loader;
-    /** YUI PHPLoader instance responsible for YUI3 loading from PHP only */
+
+    /**
+     * @var stdClass YUI PHPLoader instance responsible for YUI3 loading from PHP only
+     */
     protected $yui3loader;
-    /** YUI loader information for YUI3 loading from javascript */
+
+    /**
+     * @var stdClass YUI loader information for YUI3 loading from javascript
+     */
     protected $M_yui_loader;
-    /** some config vars exposed in JS, please no secret stuff there */
+
+    /**
+     * @var array Some config vars exposed in JS, please no secret stuff there
+     */
     protected $M_cfg;
-    /** stores debug backtraces from when JS modules were included in the page */
+
+    /**
+     * @var array Stores debug backtraces from when JS modules were included in the page
+     */
     protected $debug_moduleloadstacktraces = array();
 
     /**
@@ -205,8 +239,8 @@ class page_requirements_manager {
     }
 
     /**
-     * This method adds yui2 modules into the yui3 JS loader-
-     * @return void
+     * This method adds yui2 modules into the yui3 JS loader so that they can
+     * be easily included for use in JavaScript.
      */
     protected function add_yui2_modules() {
         //note: this function is definitely not perfect, because
@@ -319,9 +353,8 @@ class page_requirements_manager {
      * @param string|moodle_url $url The path to the .js file, relative to $CFG->dirroot / $CFG->wwwroot.
      *      For example '/mod/mymod/customscripts.js'; use moodle_url for external scripts
      * @param bool $inhead initialise in head
-     * @return void
      */
-    public function js($url, $inhead=false) {
+    public function js($url, $inhead = false) {
         $url = $this->js_fix_url($url);
         $where = $inhead ? 'head' : 'footer';
         $this->jsincludes[$where][$url->out()] = $url;
@@ -342,7 +375,6 @@ class page_requirements_manager {
      * is put into the page header, otherwise it is loaded in the page footer.
      *
      * @param string|array $libname the name of the YUI2 library you require. For example 'autocomplete'.
-     * @return void
      */
     public function yui2_lib($libname) {
         $libnames = (array)$libname;
@@ -353,6 +385,7 @@ class page_requirements_manager {
 
     /**
      * Returns the actual url through which a script is served.
+     *
      * @param moodle_url|string $url full moodle url, or shortened path to script
      * @return moodle_url
      */
@@ -380,6 +413,7 @@ class page_requirements_manager {
 
     /**
      * Find out if JS module present and return details.
+     *
      * @param string $component name of component in frankenstyle, ex: core_group, mod_forum
      * @return array description of module or null if not found
      */
@@ -388,7 +422,6 @@ class page_requirements_manager {
 
         $module = null;
 
-
         if (strpos($component, 'core_') === 0) {
             // must be some core stuff - list here is not complete, this is just the stuff used from multiple places
             // so that we do nto have to repeat the definition of these modules over and over again
@@ -488,7 +521,8 @@ class page_requirements_manager {
 
     /**
      * Append YUI3 module to default YUI3 JS loader.
-     * The structure of module array is described at http://developer.yahoo.com/yui/3/yui/:
+     * The structure of module array is described at {@link http://developer.yahoo.com/yui/3/yui/}
+     *
      * @param string|array $module name of module (details are autodetected), or full module specification as array
      * @return void
      */
@@ -616,6 +650,7 @@ class page_requirements_manager {
     /**
      * Add theme stylkesheet to page - do not use from plugin code,
      * this should be called only from the core renderer!
+     *
      * @param moodle_url $stylesheet
      * @return void
      */
@@ -667,9 +702,9 @@ class page_requirements_manager {
      * @param array $arguments and array of arguments to be passed to the function.
      *      When generating the function call, this will be escaped using json_encode,
      *      so passing objects and arrays should work.
-     * @param bool $ondomready
-     * @param int $delay
-     * @return void
+     * @param bool $ondomready If tru the function is only called when the dom is
+     *      ready for manipulation.
+     * @param int $delay The delay before the function is called.
      */
     public function js_function_call($function, array $arguments = null, $ondomready = false, $delay = 0) {
         $where = $ondomready ? 'ondomready' : 'normal';
@@ -739,7 +774,6 @@ class page_requirements_manager {
      *      already loaded.
      * @param bool $ondomready wait for dom ready (helps with some IE problems when modifying DOM)
      * @param array $module JS module specification array
-     * @return void
      */
     public function js_init_call($function, array $extraarguments = null, $ondomready = false, array $module = null) {
         $jscode = js_writer::function_call_with_Y($function, $extraarguments);
@@ -761,7 +795,6 @@ class page_requirements_manager {
      * @param string $jscode
      * @param bool $ondomready wait for dom ready (helps with some IE problems when modifying DOM)
      * @param array $module JS module specification array
-     * @return void
      */
     public function js_init_code($jscode, $ondomready = false, array $module = null) {
         $jscode = trim($jscode, " ;\n"). ';';
@@ -812,7 +845,7 @@ class page_requirements_manager {
      *     alert(M.str.moodle.fullnamedisplay);
      *
      * To substitute the placeholder at client side, use M.util.get_string()
-     * function. It implements the same logic as {@see get_string()}:
+     * function. It implements the same logic as {@link get_string()}:
      *
      *     // require the string in PHP but keep {$a} as it is
      *     $PAGE->requires->string_for_js('fullnamedisplay', 'moodle');
@@ -905,7 +938,6 @@ class page_requirements_manager {
      * @param string $event A valid DOM event (click, mousedown, change etc.)
      * @param string $function The name of the function to call
      * @param array  $arguments An optional array of argument parameters to pass to the function
-     * @return void
      */
     public function event_handler($selector, $event, $function, array $arguments = null) {
         $this->eventhandlers[] = array('selector'=>$selector, 'event'=>$event, 'function'=>$function, 'arguments'=>$arguments);
@@ -944,7 +976,7 @@ class page_requirements_manager {
 
     /**
      * Returns js code to be executed when Y is available.
-     * @return unknown_type
+     * @return string
      */
     protected function get_javascript_init_code() {
         if (count($this->jsinitcode)) {
@@ -1028,6 +1060,7 @@ class page_requirements_manager {
 
     /**
      * Returns html tags needed for inclusion of theme CSS
+     *
      * @return string
      */
     protected function get_css_code() {
@@ -1057,6 +1090,7 @@ class page_requirements_manager {
 
     /**
      * Adds extra modules specified after printing of page header
+     *
      * @return string
      */
     protected function get_extra_modules_code() {
@@ -1205,14 +1239,18 @@ class page_requirements_manager {
     }
 
     /**
-     * @return boolean Have we already output the code in the <head> tag?
+     * Have we already output the code in the <head> tag?
+     *
+     * @return bool
      */
     public function is_head_done() {
         return $this->headdone;
     }
 
     /**
-     * @return boolean Have we already output the code at the start of the <body> tag?
+     * Have we already output the code at the start of the <body> tag?
+     *
+     * @return bool
      */
     public function is_top_of_body_done() {
         return $this->topofbodydone;
@@ -1221,7 +1259,6 @@ class page_requirements_manager {
 
 /**
  * Invalidate all server and client side JS caches.
- * @return void
  */
 function js_reset_all_caches() {
     global $CFG;
@@ -1229,5 +1266,4 @@ function js_reset_all_caches() {
 
     set_config('jsrev', empty($CFG->jsrev) ? 1 : $CFG->jsrev+1);
     fulldelete("$CFG->cachedir/js");
-}
-
+}
\ No newline at end of file