MDL-40313 Fix code and doc checker warnings.

mod/quiz/editlib.php

@@ -1111,6 +1111,7 @@ class quiz_question_bank_view extends question_bank_view {
     protected $quizhasattempts = false;
     /** @var object the quiz settings. */
     protected $quiz = false;
+    /** @var int The maximum displayed length of the category info. */
     const MAX_TEXT_LENGTH = 200;
 
     /**
@@ -1206,13 +1207,15 @@ class quiz_question_bank_view extends question_bank_view {
 
     /**
      * prints a form to choose categories
+     * @param string $categoryandcontext 'categoryID,contextID'.
      * @deprecated since Moodle 2.6 MDL-40313.
      * @see question_bank_search_condition_category
      * @todo MDL-41978 This will be deleted in Moodle 2.8
      */
     protected function print_choose_category_message($categoryandcontext) {
         global $OUTPUT;
-        debugging('print_choose_category_message() is deprecated, please use question_bank_search_condition_category instead.', DEBUG_DEVELOPER);
+        debugging('print_choose_category_message() is deprecated, ' .
+                'please use question_bank_search_condition_category instead.', DEBUG_DEVELOPER);
         echo $OUTPUT->box_start('generalbox questionbank');
         $this->display_category_form($this->contexts->having_one_edit_tab_cap('edit'),
                 $this->baseurl, $categoryandcontext);
@@ -1236,7 +1239,7 @@ class quiz_question_bank_view extends question_bank_view {
             echo $searchcondition->display_options($this);
         }
         $this->display_advanced_search_form();
-        $go = html_writer::empty_tag('input', array('type'=>'submit', 'value'=>get_string('go')));
+        $go = html_writer::empty_tag('input', array('type' => 'submit', 'value' => get_string('go')));
         echo html_writer::tag('noscript', html_writer::tag('div', $go), array('class' => 'inline'));
         echo html_writer::end_div();
         echo html_writer::end_tag('form');

question/classes/bank_search_condition.php

@@ -1,17 +1,47 @@
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+
+/**
+ * Defines an abstract class for filtering/searching the question bank.
+ *
+ * @package   core_question
+ * @copyright 2013 Ray Morris
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+defined('MOODLE_INTERNAL') || die();
 
 /**
  * An abstract class for filtering/searching questions.
- * See also init_search_conditions
+ *
+ * See also {@link question_bank_view::init_search_conditions()}.
+ * @copyright 2013 Ray Morris
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 abstract class core_question_bank_search_condition {
     /**
-     * @return string An SQL fragment to be ANDed into the WHERE clause to filter which questions are shown
+     * Return an SQL fragment to be ANDed into the WHERE clause to filter which questions are shown.
+     * @return string SQL fragment. Must use named parameters.
      */
     public abstract function where();
 
     /**
-     * @return array Parameters to be bound to the above WHERE clause fragment
+     * Return parameters to be bound to the above WHERE clause fragment.
+     * @return array parameter name => value.
      */
     public function params() {
         return array();

question/classes/bank_search_condition_category.php

@@ -1,27 +1,69 @@
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+
+/**
+ * A search class to control from which category questions are listed.
+ *
+ * @package   core_question
+ * @copyright 2013 Ray Morris
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+defined('MOODLE_INTERNAL') || die();
+
 /**
  *  This class controls from which category questions are listed.
  *
- * @package    moodlecore
+ * @copyright 2013 Ray Morris
- * @subpackage questionbank
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * @copyright  2013 Tim Hunt, Ray Morris and others {@link http://moodle.com}
- * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class core_question_bank_search_condition_category extends core_question_bank_search_condition {
+    /** @var stdClass The course record. */
+    protected $course;
+
+    /** @var stdClass The category record. */
     protected $category;
+
+    /** @var array of contexts. */
+    protected $contexts;
+
+    /** @var bool Whether to include questions from sub-categories. */
     protected $recurse;
+
+    /** @var string SQL fragment to add to the where clause. */
     protected $where;
+
+    /** @var array query param used in where. */
     protected $params;
+
+    /** @var string categoryID,contextID as used with question_bank_view->display(). */
     protected $cat;
 
+    /** @var int The maximum displayed length of the category info. */
+    protected $maxinfolength;
+
     /**
      * Constructor
      * @param string     $cat           categoryID,contextID as used with question_bank_view->display()
-     * @param boolean    $recurse       Whether to include questions from sub-categories
+     * @param bool       $recurse       Whether to include questions from sub-categories
      * @param array      $contexts      Context objects as used by question_category_options()
      * @param moodle_url $baseurl       The URL the form is submitted to
      * @param stdClass   $course        Course record
-     * @param integer    $maxinfolength The maximum displayed length of the category info
+     * @param integer    $maxinfolength The maximum displayed length of the category info.
      */
     public function __construct($cat = null, $recurse = false, $contexts, $baseurl, $course, $maxinfolength = null) {
         $this->cat = $cat;
@@ -50,16 +92,10 @@ class core_question_bank_search_condition_category extends core_question_bank_se
         $this->where = 'q.category ' . $catidtest;
     }
 
-    /**
-     * @returns string SQL fragment to be ANDed to the where clause to select which category of questions to display
-     */
     public function where() {
         return  $this->where;
     }
 
-    /**
-     * @returns array Parameters to be bound to the SQL query to select which category of questions to display
-     */
     public function params() {
         return $this->params;
     }
@@ -87,7 +123,11 @@ class core_question_bank_search_condition_category extends core_question_bank_se
     }
 
     /**
-     * Display the drop down to select the category
+     * Display the drop down to select the category.
+     *
+     * @param array $contexts of contexts that can be accessed from here.
+     * @param moodle_url $pageurl the URL of this page.
+     * @param string $current 'categoryID,contextID'.
      */
     protected function display_category_form($contexts, $pageurl, $current) {
         global $OUTPUT;
@@ -127,6 +167,7 @@ class core_question_bank_search_condition_category extends core_question_bank_se
 
     /**
      * Print the category description
+     * @param stdClass $category the category information form the database.
      */
     protected function print_category_info($category) {
         $formatoptions = new stdClass();

question/classes/bank_search_condition_hide.php

@@ -1,13 +1,46 @@
 <?php
+// This file is part of Moodle - http://moodle.org/
+//
+// Moodle is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// Moodle is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+
+
 /**
- *  This class controls whether hidden / deleted questions are hidden in the list.
+ * A search class to control whether hidden / deleted questions are hidden in the list.
+ *
+ * @package   core_question
+ * @copyright 2013 Ray Morris
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
+defined('MOODLE_INTERNAL') || die();
+
+/**
+ * This class controls whether hidden / deleted questions are hidden in the list.
+ *
+ * @copyright 2013 Ray Morris
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class core_question_bank_search_condition_hide extends core_question_bank_search_condition {
-    protected $where  = '';
+    /** @var bool Whether to include old "deleted" questions. */
     protected $hide;
 
+    /** @var string SQL fragment to add to the where clause. */
+    protected $where;
+
     /**
-     * @param bool $hide include old "deleted" questions.
+     * Constructor.
+     * @param bool $hide whether to include old "deleted" questions.
      */
     public function __construct($hide = true) {
         $this->hide = $hide;
@@ -16,9 +49,6 @@ class core_question_bank_search_condition_hide extends core_question_bank_search
         }
     }
 
-    /**
-     * @return string An SQL fragment to be ANDed into the WHERE clause to show or hide deleted/hidden questions
-     */
     public function where() {
         return  $this->where;
     }

question/editlib.php

@@ -898,6 +898,7 @@ class question_bank_view {
     protected $countsql;
     protected $loadsql;
     protected $sqlparams;
+    /** @var array of \core_question\bank\search\condition objects. */
     protected $searchconditions = array();
 
     /**
@@ -1158,6 +1159,9 @@ class question_bank_view {
 
     /**
      * Create the SQL query to retrieve the indicated questions
+     * @param stdClass $category no longer used.
+     * @param bool $recurse no longer used.
+     * @param bool $showhidden no longer used.
      * @deprecated since Moodle 2.7 MDL-40313.
      * @see build_query()
      * @see question_bank_search_condition
@@ -1315,6 +1319,7 @@ class question_bank_view {
 
     /**
      * prints category information
+     * @param stdClass $category the category row from the database.
      * @deprecated since Moodle 2.7 MDL-40313.
      * @see core_question_bank_search_condition_category
      * @todo MDL-41978 This will be deleted in Moodle 2.8
@@ -1329,7 +1334,7 @@ class question_bank_view {
     }
 
     /**
-     * prints a form to choose categories
+     * Prints a form to choose categories
      * @deprecated since Moodle 2.7 MDL-40313.
      * @see core_question_bank_search_condition_category
      * @todo MDL-41978 This will be deleted in Moodle 2.8
@@ -1349,6 +1354,10 @@ class question_bank_view {
     }
 
     /**
+     * Display the options form.
+     * @param bool $recurse no longer used.
+     * @param bool $showhidden no longer used.
+     * @param bool $showquestiontext whether to show the question text.
      * @deprecated since Moodle 2.7 MDL-40313.
      * @see display_options_form
      * @todo MDL-41978 This will be deleted in Moodle 2.8
@@ -1367,7 +1376,8 @@ class question_bank_view {
      * @todo MDL-41978 This will be deleted in Moodle 2.8
      */
     protected function display_category_form_checkbox($name, $value, $label) {
-        debugging('display_category_form_checkbox() is deprecated, please use core_question_bank_search_condition_category instead.', DEBUG_DEVELOPER);
+        debugging('display_category_form_checkbox() is deprecated, ' .
+                'please use core_question_bank_search_condition_category instead.', DEBUG_DEVELOPER);
         echo '<div><input type="hidden" id="' . $name . '_off" name="' . $name . '" value="0" />';
         echo '<input type="checkbox" id="' . $name . '_on" name="' . $name . '" value="1"';
         if ($value) {
@@ -1437,17 +1447,19 @@ class question_bank_view {
     }
 
     /**
-    * Prints the table of questions in a category with interactions
+     * Prints the table of questions in a category with interactions
-    *
+     *
-    * @param object $course   The course object
+     * @param array      $contexts    Not used!
-    * @param int $categoryid  The id of the question category to be displayed
+     * @param moodle_url $pageurl     The URL to reload this page.
-    * @param int $cm      The course module record if we are in the context of a particular module, 0 otherwise
+     * @param string     $categoryandcontext 'categoryID,contextID'.
-    * @param int $recurse     This is 1 if subcategories should be included, 0 otherwise
+     * @param stdClass   $cm          Not used!
-    * @param int $page        The number of the page to be displayed
+     * @param bool       $recurse     Whether to include subcategories.
-    * @param int $perpage     Number of questions to show per page
+     * @param int        $page        The number of the page to be displayed
-    * @param bool $showhidden   True if also hidden questions should be displayed
+     * @param int        $perpage     Number of questions to show per page
-    * @param bool $showquestiontext whether the text of each question should be shown in the list. Deprecated.
+     * @param bool       $showhidden  whether deleted questions should be displayed.
-    */
+     * @param bool       $showquestiontext whether the text of each question should be shown in the list. Deprecated.
+     * @param array      $addcontexts contexts where the user is allowed to add new questions.
+     */
     protected function display_question_list($contexts, $pageurl, $categoryandcontext,
             $cm = null, $recurse=1, $page=0, $perpage=100, $showhidden=false,
             $showquestiontext = false, $addcontexts = array()) {
@@ -1707,6 +1719,10 @@ class question_bank_view {
         }
     }
 
+    /**
+     * Add another search control to this view.
+     * @param core_question_bank_search_condition $searchcondition the condition to add.
+     */
     public function add_searchcondition($searchcondition) {
         $this->searchconditions[] = $searchcondition;
     }