L-electron-Rare/moodle
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

MDL-66754 question engine: fix lots of PHPdoc errors

Browse Source 
This fixes essentially all the things PHPstorm was warning about in
question/engine/datalib.php and question/engine/questionusage.php.
This commit is contained in:
Tim Hunt
2019-09-24 10:25:29 +01:00
parent 7b1b478761
commit 824d1f8f52
3 changed files with 140 additions and 54 deletions
Download Patch File Download Diff File Expand all files Collapse all files
question/engine/datalib.php
+47 -27
View File
@@ -25,9 +25,6 @@
* The exception to this is some of the reporting methods, like
* {@link question_engine_data_mapper::load_attempts_at_question()}.
*
* (TODO, probably we should split this class up, so that it has no public
* methods. They should all be moved to a new public class.)
*
* A note for future reference. This code is pretty efficient but there are some
* potential optimisations that could be contemplated, at the cost of making the
* code more complex:
@@ -236,7 +233,7 @@ class question_engine_data_mapper {
*
* Private method, only for use by other parts of the question engine.
*
* @param question_attempt_step $qa the step to store.
* @param question_attempt_step $step the step to store.
* @param int $questionattemptid the question attept id this step belongs to.
* @param int $seq the sequence number of this stop.
* @param context $context the context of the owning question_usage_by_activity.
@@ -311,7 +308,7 @@ class question_engine_data_mapper {
* Private method, only for use by other parts of the question engine.
*
* @param int $stepid the id of the step to load.
* @param question_attempt_step the step that was loaded.
* @return question_attempt_step the step that was loaded.
*/
public function load_question_attempt_step($stepid) {
$records = $this->db->get_recordset_sql("
@@ -357,7 +354,7 @@ WHERE
* wish to load one qa, in which case you may call this method.
*
* @param int $questionattemptid the id of the question attempt to load.
* @param question_attempt the question attempt that was loaded.
* @return question_attempt the question attempt that was loaded.
*/
public function load_question_attempt($questionattemptid) {
$records = $this->db->get_recordset_sql("
@@ -419,7 +416,7 @@ ORDER BY
* rather than calling this method directly.
*
* @param int $qubaid the id of the usage to load.
* @param question_usage_by_activity the usage that was loaded.
* @return question_usage_by_activity the usage that was loaded.
*/
public function load_questions_usage_by_activity($qubaid) {
$records = $this->db->get_recordset_sql("
@@ -695,7 +692,7 @@ ORDER BY
*
* @param qubaid_condition $qubaids used to restrict which usages are included
* in the query. See {@link qubaid_condition}.
* @param int $slot The slot for the questions you want to konw about.
* @param int $slot The slot for the questions you want to know about.
* @param int $questionid (optional) Only return attempts that were of this specific question.
* @param string $summarystate the summary state of interest, or 'all'.
* @param string $orderby the column to order by.
@@ -1019,11 +1016,11 @@ ORDER BY
}
/**
* Delete all the steps for a question attempt.
* Delete some steps of a question attempt.
*
* Private method, only for use by other parts of the question engine.
*
* @param int $qaids question_attempt id.
* @param array $stepids array of step ids to delete.
* @param context $context the context that the $quba belongs to.
*/
public function delete_steps($stepids, $context) {
@@ -1084,7 +1081,8 @@ ORDER BY
*
* @param int $qubaid the question usage id.
* @param int $questionid the question id.
* @param int $sessionid the question_attempt id.
* @param int $qaid the question_attempt id.
* @param int $slot the slot number of the question attempt to update.
* @param bool $newstate the new state of the flag. true = flagged.
*/
public function update_question_attempt_flag($qubaid, $questionid, $qaid, $slot, $newstate) {
@@ -1100,7 +1098,8 @@ ORDER BY
* Get all the WHEN 'x' THEN 'y' terms needed to convert the question_attempt_steps.state
* column to a summary state. Use this like
* CASE qas.state {$this->full_states_to_summary_state_sql()} END AS summarystate,
* @param string SQL fragment.
*
* @return string SQL fragment.
*/
protected function full_states_to_summary_state_sql() {
$sql = '';
@@ -1119,7 +1118,8 @@ ORDER BY
* @param string $summarystate one of
* inprogress, needsgrading, manuallygraded or autograded
* @param bool $equal if false, do a NOT IN test. Default true.
* @return string SQL fragment.
* @param string $prefix used in the call to $DB->get_in_or_equal().
* @return array as returned by $DB->get_in_or_equal().
*/
public function in_summary_state_test($summarystate, $equal = true, $prefix = 'summarystates') {
$states = question_state::get_all_for_summary_state($summarystate);
@@ -1307,17 +1307,23 @@ class question_engine_unit_of_work implements question_usage_observer {
protected $modified = false;
/**
* @var array list of slot => {@link question_attempt}s that
* @var question_attempt[] list of slot => {@link question_attempt}s that
* have been added to the usage.
*/
protected $attemptsadded = array();
/**
* @var array list of slot => {@link question_attempt}s that
* @var question_attempt[] list of slot => {@link question_attempt}s that
* were already in the usage, and which have been modified.
*/
protected $attemptsmodified = array();
/**
* @var question_attempt[] list of slot => {@link question_attempt}s that
* have been added to the usage.
*/
protected $attemptsdeleted = array();
/**
* @var array of array(question_attempt_step, question_attempt id, seq number)
* of steps that have been added to question attempts in this usage.
@@ -1331,7 +1337,7 @@ class question_engine_unit_of_work implements question_usage_observer {
protected $stepsmodified = array();
/**
* @var array list of question_attempt_step.id => question_attempt_step of steps
* @var question_attempt_step[] list of question_attempt_step.id => question_attempt_step of steps
* that were previously stored in the database, but which are no longer required.
*/
protected $stepsdeleted = array();
@@ -1504,13 +1510,15 @@ class question_engine_unit_of_work implements question_usage_observer {
}
/**
* Determine if a step is new. If so get its array key.
*
* @param question_attempt_step $step a step
* @return int|false if the step is in the list of steps to be added, return
* the key, otherwise return false.
*/
protected function is_step_added(question_attempt_step $step) {
foreach ($this->stepsadded as $key => $data) {
list($addedstep, $qaid, $seq) = $data;
list($addedstep) = $data;
if ($addedstep === $step) {
return $key;
}
@@ -1519,13 +1527,15 @@ class question_engine_unit_of_work implements question_usage_observer {
}
/**
* Determine if a step is modified. If so get its array key.
*
* @param question_attempt_step $step a step
* @return int|false if the step is in the list of steps to be modified, return
* the key, otherwise return false.
*/
protected function is_step_modified(question_attempt_step $step) {
foreach ($this->stepsmodified as $key => $data) {
list($modifiedstep, $qaid, $seq) = $data;
list($modifiedstep) = $data;
if ($modifiedstep === $step) {
return $key;
}
@@ -1648,10 +1658,12 @@ class question_file_saver implements question_response_files {
protected $value = null;
/**
* Constuctor.
* Constructor.
*
* @param int $draftitemid the draft area to save the files from.
* @param string $component the component for the file area to save into.
* @param string $filearea the name of the file area to save into.
* @param string $text optional content containing file links.
*/
public function __construct($draftitemid, $component, $filearea, $text = null) {
$this->draftitemid = $draftitemid;
@@ -1661,10 +1673,13 @@ class question_file_saver implements question_response_files {
}
/**
* Compute the value that should be stored in the question_attempt_step_data
* table. Contains a hash that (almost) uniquely encodes all the files.
* Compute the value that should be stored in the question_attempt_step_data table.
*
* Contains a hash that (almost) uniquely encodes all the files.
*
* @param int $draftitemid the draft file area itemid.
* @param string $text optional content containing file links.
* @return string the value.
*/
protected function compute_value($draftitemid, $text) {
global $USER;
@@ -1708,7 +1723,9 @@ class question_file_saver implements question_response_files {
/**
* Actually save the files.
*
* @param integer $itemid the item id for the file area to save into.
* @param context $context the context where the files should be saved.
*/
public function save_files($itemid, $context) {
file_save_draft_area_files($this->draftitemid, $context->id,
@@ -1836,9 +1853,14 @@ class question_file_loader implements question_response_files {
abstract class qubaid_condition {
/**
* @return string the SQL that needs to go in the FROM clause when trying
* to select records from the 'question_attempts' table based on the
* Get the SQL fragment to go in a FROM clause.
*
* The SQL that needs to go in the FROM clause when trying
* to select records from the 'question_attempts' table based on this
* qubaid_condition.
*
* @param string $alias
* @return string SQL fragment.
*/
public abstract function from_question_attempts($alias);
@@ -1846,7 +1868,7 @@ abstract class qubaid_condition {
public abstract function where();
/**
* @return the params needed by a query that uses
* @return array the params needed by a query that uses
* {@link from_question_attempts()} and {@link where()}.
*/
public abstract function from_where_params();
@@ -1858,7 +1880,7 @@ abstract class qubaid_condition {
public abstract function usage_id_in();
/**
* @return the params needed by a query that uses {@link usage_id_in()}.
* @return array the params needed by a query that uses {@link usage_id_in()}.
*/
public abstract function usage_id_in_params();
@@ -1899,8 +1921,6 @@ class qubaid_list extends qubaid_condition {
}
public function where() {
global $DB;
if (is_null($this->columntotest)) {
throw new coding_exception('Must call from_question_attempts before where().');
}
question/engine/questionusage.php
+90 -25
View File
@@ -385,6 +385,7 @@ class question_usage_by_activity {
* The values are arrays with two items, title and content. Each of these
* will be either a string, or a renderable.
*
* @param question_display_options $options display options to apply.
* @return array as described above.
*/
public function get_summary_information(question_display_options $options) {
@@ -393,21 +394,30 @@ class question_usage_by_activity {
}
/**
* @return string a simple textual summary of the question that was asked.
* Get a simple textual summary of the question that was asked.
*
* @param int $slot the slot number of the question to summarise.
* @return string the question summary.
*/
public function get_question_summary($slot) {
return $this->get_question_attempt($slot)->get_question_summary();
}
/**
* @return string a simple textual summary of response given.
* Get a simple textual summary of response given.
*
* @param int $slot the slot number of the question to get the response summary for.
* @return string the response summary.
*/
public function get_response_summary($slot) {
return $this->get_question_attempt($slot)->get_response_summary();
}
/**
* @return string a simple textual summary of the correct resonse.
* Get a simple textual summary of the correct response to a question.
*
* @param int $slot the slot number of the question to get the right answer summary for.
* @return string the right answer summary.
*/
public function get_right_answer_summary($slot) {
return $this->get_question_attempt($slot)->get_right_answer_summary();
@@ -499,9 +509,8 @@ class question_usage_by_activity {
* For internal use only. Used when reloading the state of a question from the
* database.
*
* @param array $records Raw records loaded from the database.
* @param int $questionattemptid The id of the question_attempt to extract.
* @return question_attempt The newly constructed question_attempt_step.
* @param int $slot the slot number of the question to replace.
* @param question_attempt $qa the question attempt to put in that place.
*/
public function replace_loaded_question_attempt_info($slot, $qa) {
$this->check_slot($slot);
@@ -543,7 +552,7 @@ class question_usage_by_activity {
* @param int $variant which variant of the question to use. Must be between
* 1 and ->get_num_variants($slot) inclusive. If not give, a variant is
* chosen at random.
* @param int $timestamp optional, the timstamp to record for this action. Defaults to now.
* @param int|null $timenow optional, the timstamp to record for this action. Defaults to now.
*/
public function start_question($slot, $variant = null, $timenow = null) {
if (is_null($variant)) {
@@ -667,7 +676,7 @@ class question_usage_by_activity {
* particular question.
*
* @param int $slot the number used to identify this question within this usage.
* @param $postdata optional, only intended for testing. Use this data
* @param array|null $postdata optional, only intended for testing. Use this data
* instead of the data from $_POST.
* @return array submitted data specific to this question.
*/
@@ -722,7 +731,8 @@ class question_usage_by_activity {
/**
* Process a specific action on a specific question.
* @param int $slot the number used to identify this question within this usage.
* @param $submitteddata the submitted data that constitutes the action.
* @param array $submitteddata the submitted data that constitutes the action.
* @param int|null $timestamp (optional) the timestamp to consider 'now'.
*/
public function process_action($slot, $submitteddata, $timestamp = null) {
$qa = $this->get_question_attempt($slot);
@@ -733,7 +743,8 @@ class question_usage_by_activity {
/**
* Process an autosave action on a specific question.
* @param int $slot the number used to identify this question within this usage.
* @param $submitteddata the submitted data that constitutes the action.
* @param array $submitteddata the submitted data that constitutes the action.
* @param int|null $timestamp (optional) the timestamp to consider 'now'.
*/
public function process_autosave($slot, $submitteddata, $timestamp = null) {
$qa = $this->get_question_attempt($slot);
@@ -743,12 +754,14 @@ class question_usage_by_activity {
}
/**
* Check that the sequence number, that detects weird things like the student
* clicking back, is OK. If the sequence check variable is not present, returns
* Check that the sequence number, that detects weird things like the student clicking back, is OK.
*
* If the sequence check variable is not present, returns
* false. If the check variable is present and correct, returns true. If the
* variable is present and wrong, throws an exception.
*
* @param int $slot the number used to identify this question within this usage.
* @param array $submitteddata the submitted data that constitutes the action.
* @param array|null $postdata (optional) data to use in place of $_POST.
* @return bool true if the check variable is present and correct. False if it
* is missing. (Throws an exception if the check fails.)
*/
@@ -767,8 +780,9 @@ class question_usage_by_activity {
/**
* Check, based on the sequence number, whether this auto-save is still required.
*
* @param int $slot the number used to identify this question within this usage.
* @param array $submitteddata the submitted data that constitutes the action.
* @param array|null $postdata the submitted data that constitutes the action.
* @return bool true if the check variable is present and correct, otherwise false.
*/
public function is_autosave_required($slot, $postdata = null) {
@@ -788,7 +802,7 @@ class question_usage_by_activity {
* Update the flagged state for all question_attempts in this usage, if their
* flagged state was changed in the request.
*
* @param $postdata optional, only intended for testing. Use this data
* @param array|null $postdata optional, only intended for testing. Use this data
* instead of the data from $_POST.
*/
public function update_question_flags($postdata = null) {
@@ -824,6 +838,7 @@ class question_usage_by_activity {
* manual grading, or changing the flag state.
*
* @param int $slot the number used to identify this question within this usage.
* @param int|null $timestamp (optional) the timestamp to consider 'now'.
*/
public function finish_question($slot, $timestamp = null) {
$qa = $this->get_question_attempt($slot);
@@ -834,6 +849,8 @@ class question_usage_by_activity {
/**
* Finish the active phase of an attempt at a question. See {@link finish_question()}
* for a fuller description of what 'finish' means.
*
* @param int|null $timestamp (optional) the timestamp to consider 'now'.
*/
public function finish_all_questions($timestamp = null) {
foreach ($this->questionattempts as $qa) {
@@ -906,7 +923,7 @@ class question_usage_by_activity {
* For internal use only.
*
* @param Iterator $records Raw records loaded from the database.
* @param int $questionattemptid The id of the question_attempt to extract.
* @param int $qubaid The id of the question usage we are loading.
* @return question_usage_by_activity The newly constructed usage.
*/
public static function load_from_records($records, $qubaid) {
@@ -952,8 +969,7 @@ class question_usage_by_activity {
/**
* A class abstracting access to the
* {@link question_usage_by_activity::$questionattempts} array.
* A class abstracting access to the {@link question_usage_by_activity::$questionattempts} array.
*
* This class snapshots the list of {@link question_attempts} to iterate over
* when it is created. If a question is added to the usage mid-iteration, it
@@ -966,15 +982,18 @@ class question_usage_by_activity {
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
*/
class question_attempt_iterator implements Iterator, ArrayAccess {
/** @var question_usage_by_activity that we are iterating over. */
protected $quba;
/** @var array of question numbers. */
/** @var array of slot numbers. */
protected $slots;
/**
* To create an instance of this class, use
* {@link question_usage_by_activity::get_attempt_iterator()}.
* @param $quba the usage to iterate over.
*
* @param question_usage_by_activity $quba the usage to iterate over.
*/
public function __construct(question_usage_by_activity $quba) {
$this->quba = $quba;
@@ -982,37 +1001,83 @@ class question_attempt_iterator implements Iterator, ArrayAccess {
$this->rewind();
}
/** @return question_attempt_step */
/**
* Standard part of the Iterator interface.
*
* @return question_attempt
*/
public function current() {
return $this->offsetGet(current($this->slots));
}
/** @return int */
/**
* Standard part of the Iterator interface.
*
* @return int
*/
public function key() {
return current($this->slots);
}
/**
* Standard part of the Iterator interface.
*/
public function next() {
next($this->slots);
}
/**
* Standard part of the Iterator interface.
*/
public function rewind() {
reset($this->slots);
}
/** @return bool */
/**
* Standard part of the Iterator interface.
*
* @return bool
*/
public function valid() {
return current($this->slots) !== false;
}
/** @return bool */
/**
* Standard part of the ArrayAccess interface.
*
* @param int $slot
* @return bool
*/
public function offsetExists($slot) {
return in_array($slot, $this->slots);
}
/** @return question_attempt_step */
/**
* Standard part of the ArrayAccess interface.
*
* @param int $slot
* @return question_attempt
*/
public function offsetGet($slot) {
return $this->quba->get_question_attempt($slot);
}
/**
* Standard part of the ArrayAccess interface.
*
* @param int $slot
* @param question_attempt $value
*/
public function offsetSet($slot, $value) {
throw new coding_exception('You are only allowed read-only access to ' .
'question_attempt::states through a question_attempt_step_iterator. Cannot set.');
}
/**
* Standard part of the ArrayAccess interface.
*
* @param int $slot
*/
public function offsetUnset($slot) {
throw new coding_exception('You are only allowed read-only access to ' .
'question_attempt::states through a question_attempt_step_iterator. Cannot unset.');
question/engine/states.php
+3 -2
View File
@@ -72,7 +72,8 @@ abstract class question_state {
/**
* Get all the states in an array.
* @return of question_state objects.
*
* @return question_state[] of question_state objects.
*/
public static function get_all() {
$states = array();
@@ -87,7 +88,7 @@ abstract class question_state {
* Get all the states in an array.
* @param string $summarystate one of the four summary states
* inprogress, needsgrading, manuallygraded or autograded.
* @return arrau of the corresponding states.
* @return array of the corresponding states.
*/
public static function get_all_for_summary_state($summarystate) {
$states = array();