MDL-47494 question General code cleanup

Remove old browser CSS.
Fix code style problems.
Add many PHPdocs.
Set @package uniformly.

question/type/ddimageortext/backup/moodle2/backup_qtype_ddimageortext_plugin.class.php

@@ -31,9 +31,9 @@ defined('MOODLE_INTERNAL') || die();
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class backup_qtype_ddimageortext_plugin extends backup_qtype_plugin {
-
     /**
      * Returns the question type this is.
+     *
      * @return string question type name, like 'ddimageortext'.
      */
     protected static function qtype_name() {

question/type/ddimageortext/backup/moodle2/restore_qtype_ddimageortext_plugin.class.php

@@ -30,13 +30,19 @@ defined('MOODLE_INTERNAL') || die();
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class restore_qtype_ddimageortext_plugin extends restore_qtype_plugin {
-
+    /**
+     * Returns the qtype name.
+     *
+     * @return string The type name
+     */
     protected static function qtype_name() {
         return 'ddimageortext';
     }
 
     /**
      * Returns the paths to be handled by the plugin at question level.
+     *
+     * @return array
      */
     protected function define_question_plugin_structure() {
 
@@ -60,6 +66,8 @@ class restore_qtype_ddimageortext_plugin extends restore_qtype_plugin {
 
     /**
      * Process the qtype/{qtypename} element.
+     *
+     * @param array|object $data Drag and drop data to work with.
      */
     public function process_dds($data) {
         global $DB;
@@ -88,6 +96,8 @@ class restore_qtype_ddimageortext_plugin extends restore_qtype_plugin {
 
     /**
      * Process the qtype/drags/drag element.
+     *
+     * @param array|object $data Drag and drop drag data to work with.
      */
     public function process_drag($data) {
         global $DB;
@@ -113,7 +123,9 @@ class restore_qtype_ddimageortext_plugin extends restore_qtype_plugin {
     }
 
     /**
-     * Process the qtype/drags/drag element.
+     * Process the qtype/drags/drop element.
+     *
+     * @param array|object $data Drad and drop drops data to work with.
      */
     public function process_drop($data) {
         global $DB;
@@ -136,8 +148,11 @@ class restore_qtype_ddimageortext_plugin extends restore_qtype_plugin {
             $this->set_mapping("{$prefix}_drops", $oldid, $newitemid);
         }
     }
+
     /**
      * Return the contents of this qtype to be processed by the links decoder.
+     *
+     * @return array
      */
     public static function define_decode_contents() {
 

question/type/ddimageortext/edit_ddimageortext_form.php

@@ -35,7 +35,6 @@ require_once($CFG->dirroot . '/question/type/ddimageortext/edit_ddtoimage_form_b
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class qtype_ddimageortext_edit_form extends qtype_ddtoimage_edit_form_base {
-
     public function qtype() {
         return 'ddimageortext';
     }

question/type/ddimageortext/edit_ddtoimage_form_base.php

@@ -17,10 +17,9 @@
 /**
  * Base class for editing form for the drag-and-drop images onto images question type.
  *
- * @package    qtype
- * @subpackage ddimageortext
- * @copyright  2011 The Open University
- * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @package   qtype_ddimageortext
+ * @copyright 2011 The Open University
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 defined('MOODLE_INTERNAL') || die();
@@ -32,13 +31,25 @@ defined('MOODLE_INTERNAL') || die();
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 abstract class qtype_ddtoimage_edit_form_base extends question_edit_form {
+    /**
+     * Maximum number of different groups of drag items there can be in a question.
+     */
     const MAX_GROUPS = 8;
+
+    /**
+     * The default starting number of drop zones.
+     */
     const START_NUM_ITEMS = 6;
+
+    /**
+     * The number of drop zones that get added at a time.
+     */
     const ADD_NUM_ITEMS = 3;
 
     /**
-     *
      * Options shared by all file pickers in the form.
+     *
+     * @return array Array of filepicker options.
      */
     public static function file_picker_options() {
         $filepickeroptions = array();
@@ -51,6 +62,7 @@ abstract class qtype_ddtoimage_edit_form_base extends question_edit_form {
 
     /**
      * definition_inner adds all specific fields to the form.
+     *
      * @param MoodleQuickForm $mform (the form being built).
      */
     protected function definition_inner($mform) {
@@ -76,9 +88,14 @@ abstract class qtype_ddtoimage_edit_form_base extends question_edit_form {
         $this->add_interactive_settings(true, true);
     }
 
+    /**
+     * Make and add drop zones to the form.
+     *
+     * @param object $mform The Moodle form object.
+     * @param int $imagerepeats The initial number of repeat elements.
+     */
     protected function definition_drop_zones($mform, $imagerepeats) {
-        $mform->addElement('header', 'dropzoneheader',
-                                            get_string('dropzoneheader', 'qtype_'.$this->qtype()));
+        $mform->addElement('header', 'dropzoneheader', get_string('dropzoneheader', 'qtype_'.$this->qtype()));
 
         $countdropzones = 0;
         if (isset($this->question->id)) {
@@ -97,16 +114,51 @@ abstract class qtype_ddtoimage_edit_form_base extends question_edit_form {
                 'nodropzone', 'adddropzone', self::ADD_NUM_ITEMS,
                 get_string('addmoredropzones', 'qtype_ddimageortext'), true);
     }
+
+    /**
+     * Returns an array with a drop zone form element.
+     *
+     * @param object $mform The Moodle form object.
+     * @param int $imagerepeats The number of repeat images.
+     * @return array Array with the dropzone element.
+     */
     abstract protected function drop_zone($mform, $imagerepeats);
 
+    /**
+     * Returns an array of default drop zone repeat options.
+     *
+     * @return array
+     */
     abstract protected function drop_zones_repeated_options();
 
+    /**
+     * Builds and adds the needed form items for draggable items.
+     *
+     * @param object $mform The Moodle form object.
+     * @param int $itemrepeatsatstart The initial number of repeat elements.
+     */
     abstract protected function definition_draggable_items($mform, $itemrepeatsatstart);
 
+    /**
+     * Creates and returns a set of form elements to make a draggable item.
+     *
+     * @param object $mform The Moodle form object.
+     * @return array An array of form elements.
+     */
     abstract protected function draggable_item($mform);
 
+    /**
+     * Returns an array of default repeat options.
+     *
+     * @return array
+     */
     abstract protected function draggable_items_repeated_options();
 
+    /**
+     * Returns an array of starting number of repeats, and the total number of repeats.
+     *
+     * @return array
+     */
     protected function get_drag_item_repeats() {
         $countimages = 0;
         if (isset($this->question->id)) {
@@ -128,8 +180,17 @@ abstract class qtype_ddtoimage_edit_form_base extends question_edit_form {
         return array($itemrepeatsatstart, $imagerepeats);
     }
 
+    /**
+     * Performce the needed JS setup for this question type.
+     */
     abstract public function js_call();
 
+    /**
+     * Checks to see if a file has been uploaded.
+     *
+     * @param string $draftitemid The draft id
+     * @return bool True if files exist, false if not.
+     */
     public static function file_uploaded($draftitemid) {
         $draftareafiles = file_get_drafarea_files($draftitemid);
         do {
@@ -141,5 +202,4 @@ abstract class qtype_ddtoimage_edit_form_base extends question_edit_form {
         return true;
     }
 
-
 }

question/type/ddimageortext/lang/en/qtype_ddimageortext.php

@@ -15,11 +15,11 @@
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
 /**
+ * Language file Drag and Drop image or text.
  *
- * @package    qtype
- * @subpackage ddimageortext
- * @copyright  2011 The Open University
- * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @package   qtype_ddimageortext
+ * @copyright 2011 The Open University
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 $string['addmoredropzones'] = 'Blanks for {no} more drop zones';
@@ -67,4 +67,4 @@ $string['summariseplace'] = '{$a->no}. {$a->text}';
 $string['summarisechoiceno'] = 'Item {$a}';
 $string['summariseplaceno'] = 'Drop zone {$a}';
 $string['xleft'] = 'Left';
-$string['ytop'] = 'Top';
\ No newline at end of file
+$string['ytop'] = 'Top';

question/type/ddimageortext/lib.php

@@ -17,10 +17,9 @@
 /**
  * Serve question type files
  *
- * @package    qtype
- * @subpackage ddimageortext
- * @copyright  Dongsheng Cai <dongsheng@moodle.com>
- * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @package   qtype_ddimageortext
+ * @copyright Dongsheng Cai <dongsheng@moodle.com>
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 
 
@@ -29,10 +28,17 @@ defined('MOODLE_INTERNAL') || die();
 
 /**
  * Checks file access for ddimageortext questions.
+ *
+ * @param object $course The course we are in
+ * @param object $cm Course module
+ * @param object $context The context object
+ * @param string $filearea the name of the file area.
+ * @param array $args the remaining bits of the file path.
+ * @param bool $forcedownload whether the user must be forced to download the file.
+ * @param array $options additional options affecting the file serving
  */
 function qtype_ddimageortext_pluginfile($course, $cm, $context, $filearea, $args, $forcedownload, array $options=array()) {
     global $CFG;
     require_once($CFG->libdir . '/questionlib.php');
-    question_pluginfile($course, $context, 'qtype_ddimageortext',
-                                                                $filearea, $args, $forcedownload, $options);
+    question_pluginfile($course, $context, 'qtype_ddimageortext', $filearea, $args, $forcedownload, $options);
 }

question/type/ddimageortext/question.php

@@ -46,12 +46,30 @@ class qtype_ddimageortext_question extends qtype_ddtoimage_question_base {
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class qtype_ddimageortext_drag_item {
+    /** @var int Drag item id */
     public $id;
+
+    /** @var string Text for the drag item */
     public $text;
+
+    /** @var int Number of the item */
     public $no;
+
+    /** @var int Group of the item */
     public $group;
+
+    /** @var bool If the drag item can be used multiple times or not */
     public $infinite;
 
+    /**
+     * Drag item object setup.
+     *
+     * @param string $alttextlabel The alt text of the drag item
+     * @param int $no Which number drag item this is
+     * @param int $group Group of the drag item
+     * @param bool $infinite True if the item can be used an unlimited number of times
+     * @param int $id id of the item
+     */
     public function __construct($alttextlabel, $no, $group = 1, $infinite = false, $id = 0) {
         $this->id = $id;
         $this->text = $alttextlabel;
@@ -59,10 +77,21 @@ class qtype_ddimageortext_drag_item {
         $this->group = $group;
         $this->infinite = $infinite;
     }
+
+    /**
+     * Returns the group of this item.
+     *
+     * @return int
+     */
     public function choice_group() {
         return $this->group;
     }
 
+    /**
+     * Creates summary text of for the drag item.
+     *
+     * @return string
+     */
     public function summarise() {
         if (trim($this->text) != '') {
             return get_string('summarisechoice', 'qtype_ddimageortext', $this);
@@ -78,11 +107,27 @@ class qtype_ddimageortext_drag_item {
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class qtype_ddimageortext_drop_zone {
+    /** @var int Number of the item */
     public $no;
+
+    /** @var string Alt text for the drop zone item */
     public $text;
+
+    /** @var int Group of the item */
     public $group;
+
+    /** @var array X and Y location of the drop zone */
     public $xy;
 
+    /**
+     * Create a drop zone object.
+     *
+     * @param string $alttextlabel The alt text of the drop zone
+     * @param int $no Which number drop zone this is
+     * @param int $group Group of the drop zone
+     * @param int $x X location
+     * @param int $y Y location
+     */
     public function __construct($alttextlabel, $no, $group = 1, $x = '', $y = '') {
         $this->no = $no;
         $this->text = $alttextlabel;
@@ -90,6 +135,11 @@ class qtype_ddimageortext_drop_zone {
         $this->xy = array($x, $y);
     }
 
+    /**
+     * Creates summary text of for the drop zone
+     *
+     * @return string
+     */
     public function summarise() {
         if (trim($this->text) != '') {
             $summariseplace =
@@ -100,4 +150,4 @@ class qtype_ddimageortext_drop_zone {
         }
         return $summariseplace;
     }
-}
\ No newline at end of file
+}

question/type/ddimageortext/questiontypebase.php

@@ -37,6 +37,11 @@ require_once($CFG->dirroot . '/question/type/gapselect/questiontypebase.php');
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class qtype_ddtoimage_base extends question_type {
+    /**
+     * Returns the choice group key.
+     *
+     * @return string
+     */
     protected function choice_group_key() {
         return 'draggroup';
     }
@@ -145,8 +150,8 @@ class qtype_ddtoimage_base extends question_type {
      * Convert files into text output in the given format.
      * This method is copied from qformat_default as a quick fix, as the method there is
      * protected.
-     * @param array
-     * @param string encoding method
+     * @param array $files
+     * @param int $indent Number of spaces to indent
      * @return string $string
      */
     public function write_files($files, $indent) {

question/type/ddimageortext/rendererbase.php

@@ -129,6 +129,14 @@ class qtype_ddtoimage_renderer_base extends qtype_with_combined_feedback_rendere
         return $output;
     }
 
+    /**
+     * Returns the URL for an image
+     *
+     * @param object $qa Question attempt object
+     * @param string $filearea File area descriptor
+     * @param int $itemid Item id to get
+     * @return string Output url, or null if not found
+     */
     protected static function get_url_for_image(question_attempt $qa, $filearea, $itemid = 0) {
         $question = $qa->get_question();
         $qubaid = $qa->get_usage_id();
@@ -154,6 +162,15 @@ class qtype_ddtoimage_renderer_base extends qtype_with_combined_feedback_rendere
         return null;
     }
 
+    /**
+     * Returns a hidden field for a qt variable
+     *
+     * @param object $qa Question attempt object
+     * @param string $varname The hidden var name
+     * @param string $value The hidden value
+     * @param array $classes Any additional css classes to apply
+     * @return array Array with field name and the html of the tag
+     */
     protected function hidden_field_for_qt_var(question_attempt $qa, $varname, $value = null,
                                                 $classes = null) {
         if ($value === null) {

question/type/ddimageortext/styles.css

@@ -18,12 +18,10 @@
     border: 1px solid black;
     cursor: move;
     background-color: #B0C4DE;
-    display: -moz-inline-stack;
     display:inline-block;
     height: auto;
     width: auto;
     zoom: 1;
-    *display: inline;
 }
 
 .que.ddimageortext .group1, form.mform fieldset#id_previewareaheader .group1 {
@@ -78,19 +76,11 @@
 .que.ddimageortext div.dragitems div.draghome, .que.ddimageortext div.dragitems div.drag,
 form.mform fieldset#id_previewareaheader div.draghome, form.mform fieldset#id_previewareaheader div.drag {
     font:13px/1.231 arial,helvetica,clean,sans-serif;
-    *font-size:small; /* for IE */
-    *font:x-small; /* for IE in quirks mode */
 }
 form.mform fieldset#id_previewareaheader div.drag.yui3-dd-dragging,
 .que.ddimageortext div.drag.yui3-dd-dragging {
     z-index: 3;
-    -moz-box-shadow: 3px 3px 4px #000;
-    -webkit-box-shadow: 3px 3px 4px #000;
     box-shadow: 3px 3px 4px #000;
-    /* For IE 8 */
-    -ms-filter: "progid:DXImageTransform.Microsoft.Shadow(Strength=4, Direction=135, Color='#000000')";
-    /* For IE 5.5 - 7 */
-    filter: progid:DXImageTransform.Microsoft.Shadow(Strength=4, Direction=135, Color='#000000');
 }
 /* Editing form. Style repeated elements*/
 /*Top*/

question/type/ddimageortext/tests/behat/behat_qtype_ddimageortext.php

@@ -46,7 +46,7 @@ class behat_qtype_ddimageortext extends behat_base {
 
     /**
      * Get the xpath for a given drop box.
-     * @param string $dragitem the number of the drop box.
+     * @param string $placenumber the number of the drop box.
      * @return string the xpath expression.
      */
     protected function drop_xpath($placenumber) {

question/type/ddimageortext/tests/helper.php

@@ -95,6 +95,8 @@ class qtype_ddimageortext_test_helper extends question_test_helper {
     }
 
     /**
+     * Make a mathematical ddimageortext question.
+     *
      * @return qtype_ddimageortext_question
      */
     public function make_ddimageortext_question_maths() {
@@ -152,12 +154,15 @@ class qtype_ddimageortext_test_helper extends question_test_helper {
         $fromform->name = 'Geography cross-section';
         $fromform->questiontext = array(
             'text' => '<p>Identify the features in this cross-section by dragging the labels into the boxes.</p>
-                       <p><em>Use the mouse to drag the boxed words into the empty boxes. Alternatively, use the tab key to select an empty box, then use the space key to cycle through the options.</em></p>',
+                       <p><em>Use the mouse to drag the boxed words into the empty boxes. '.
+                      'Alternatively, use the tab key to select an empty box, '.
+                      'then use the space key to cycle through the options.</em></p>',
             'format' => FORMAT_HTML,
         );
         $fromform->defaultmark = 1;
         $fromform->generalfeedback = array(
-            'text' => '<p>More information about the major features of the Earth\'s surface can be found in Block 3, Section 6.2.</p>',
+            'text' => '<p>More information about the major features of the Earth\'s surface '.
+                      'can be found in Block 3, Section 6.2.</p>',
             'format' => FORMAT_HTML,
         );
         $fromform->bgimage = $bgdraftitemid;
@@ -197,7 +202,7 @@ class qtype_ddimageortext_test_helper extends question_test_helper {
 
         test_question_maker::set_standard_combined_feedback_form_data($fromform);
 
-        $fromform->penalty ='0.3333333';
+        $fromform->penalty = '0.3333333';
         $fromform->hint = array(
             array(
                 'text' => '<p>Incorrect placements will be removed.</p>',
@@ -205,10 +210,12 @@ class qtype_ddimageortext_test_helper extends question_test_helper {
             ),
             array(
                 'text' => '<ul>
-                           <li>The abyssal plain is a flat almost featureless expanse of ocean floor 4km to 6km below sea-level.</li>
+                           <li>The abyssal plain is a flat almost featureless expanse of ocean '.
+                           'floor 4km to 6km below sea-level.</li>
                            <li>The continental rise is the gently sloping part of the ocean floor beyond the continental slope.</li>
                            <li>The continental shelf is the gently sloping ocean floor just offshore from the land.</li>
-                           <li>The continental slope is the relatively steep part of the ocean floor beyond the continental shelf.</li>
+                           <li>The continental slope is the relatively steep part of the ocean floor '.
+                           'beyond the continental shelf.</li>
                            <li>A mid-ocean ridge is a broad submarine ridge several kilometres high.</li>
                            <li>A mountain belt is a long range of mountains.</li>
                            <li>An island arc is a chain of volcanic islands.</li>
@@ -222,10 +229,12 @@ class qtype_ddimageortext_test_helper extends question_test_helper {
             ),
             array(
                 'text' => '<ul>
-                           <li>The abyssal plain is a flat almost featureless expanse of ocean floor 4km to 6km below sea-level.</li>
+                           <li>The abyssal plain is a flat almost featureless expanse of ocean '.
+                           'floor 4km to 6km below sea-level.</li>
                            <li>The continental rise is the gently sloping part of the ocean floor beyond the continental slope.</li>
                            <li>The continental shelf is the gently sloping ocean floor just offshore from the land.</li>
-                           <li>The continental slope is the relatively steep part of the ocean floor beyond the continental shelf.</li>
+                           <li>The continental slope is the relatively steep part of the ocean floor '.
+                           'beyond the continental shelf.</li>
                            <li>A mid-ocean ridge is a broad submarine ridge several kilometres high.</li>
                            <li>A mountain belt is a long range of mountains.</li>
                            <li>An island arc is a chain of volcanic islands.</li>

question/type/ddimageortext/yui/src/form/js/form.js

@@ -351,4 +351,3 @@ M.qtype_ddimageortext = M.qtype_ddimageortext || {};
 M.qtype_ddimageortext.init_form = function(config) {
     return new DDIMAGEORTEXT_FORM(config);
 };
-

question/type/ddmarker/backup/moodle2/backup_qtype_ddmarker_plugin.class.php

@@ -31,9 +31,9 @@ defined('MOODLE_INTERNAL') || die();
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class backup_qtype_ddmarker_plugin extends backup_qtype_plugin {
-
     /**
      * Get the name of this question type.
+     *
      * @return string the question type, like 'ddmarker'.
      */
     protected static function qtype_name() {

question/type/ddmarker/backup/moodle2/restore_qtype_ddmarker_plugin.class.php

@@ -32,13 +32,19 @@ defined('MOODLE_INTERNAL') || die();
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class restore_qtype_ddmarker_plugin extends restore_qtype_plugin {
-
+    /**
+     * Returns the qtype name.
+     *
+     * @return string The type name
+     */
     protected static function qtype_name() {
         return 'ddmarker';
     }
 
     /**
      * Returns the paths to be handled by the plugin at question level.
+     *
+     * @return array
      */
     protected function define_question_plugin_structure() {
 
@@ -61,7 +67,9 @@ class restore_qtype_ddmarker_plugin extends restore_qtype_plugin {
     }
 
     /**
-     * Process the qtype/{qtypename} element
+     * Process the qtype/{qtypename} element.
+     *
+     * @param array|object $data Drag and drop data to work with.
      */
     public function process_dds($data) {
         global $DB;
@@ -90,6 +98,8 @@ class restore_qtype_ddmarker_plugin extends restore_qtype_plugin {
 
     /**
      * Process the qtype/drags/drag element.
+     *
+     * @param array|object $data Drag and drop drag data to work with.
      */
     public function process_drag($data) {
         global $DB;
@@ -115,7 +125,9 @@ class restore_qtype_ddmarker_plugin extends restore_qtype_plugin {
     }
 
     /**
-     * Process the qtype/drags/drag element.
+     * Process the qtype/drags/drop element.
+     *
+     * @param array|object $data Drag and drop drops data to work with.
      */
     public function process_drop($data) {
         global $DB;
@@ -141,6 +153,8 @@ class restore_qtype_ddmarker_plugin extends restore_qtype_plugin {
 
     /**
      * Return the contents of this qtype to be processed by the links decoder
+     *
+     * @return array
      */
     public static function define_decode_contents() {
 

question/type/ddmarker/edit_ddmarker_form.php

@@ -39,7 +39,6 @@ define('QTYPE_DDMARKER_ALLOWED_TAGS_IN_MARKER', '<br><i><em><b><strong><sup><sub
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later