Skip to content

Commit

Permalink
MDL-77464 questions: update comments in question_attempt_step
Browse files Browse the repository at this point in the history 
The class comment had some inaccuracies which I fixed.
I also replaced all uses of @link with @see.
  • Loading branch information
@timhunt
timhunt committed Mar 7, 2023
1 parent 62cfa26 commit 33e98af
Showing 1 changed file with 36 additions and 30 deletions.
66 changes: 36 additions & 30 deletions question/engine/questionattemptstep.php
View file
Expand Up @@ -28,19 +28,18 @@


/**
* Stores one step in a {@link question_attempt}.
* Stores one step in a {@see question_attempt}.
*
* The most important attributes of a step are the state, which is one of the
* {@link question_state} constants, the fraction, which may be null, or a
* {@see question_state} constants, the fraction, which may be null, or a
* number bewteen the attempt's minfraction and maxfraction, and the array of submitted
* data, about which more later.
*
* A step also tracks the time it was created, and the user responsible for
* creating it.
*
* The submitted data is basically just an array of name => value pairs, with
* certain conventions about the to divide the variables into four = two times two
* categories.
* certain conventions about the to divide the variables into five = 2 x 2 + 1 categories.
*
* Variables may either belong to the behaviour, in which case the
* name starts with a '-', or they may belong to the question type in which case
Expand All @@ -50,15 +49,21 @@
* which case the name does not start with an _, or they are cached values that
* were created during processing, in which case the name does start with an _.
*
* That is, each name will start with one of '', '_'. '-' or '-_'. The remainder
* of the name should match the regex [a-z][a-z0-9]*.
* In addition, we can store 'metadata', typically only in the first step of a
* question attempt. These are stored with the initial characters ':_'.
*
* These variables can be accessed with {@link get_behaviour_var()} and {@link get_qt_var()},
* That is, each name will start with one of '', '_', '-', '-_' or ':_'. The remainder
* of the name was supposed to match the regex [a-z][a-z0-9]* - but this has never
* been enforced. Question types exist which break this rule. E.g. qtype_combined.
* Perhpas now, an accurate regex would be [a-z][a-z0-9_:]*.
*
* These variables can be accessed with {@see get_behaviour_var()} and {@see get_qt_var()},
* - to be clear, ->get_behaviour_var('x') gets the variable with name '-x' -
* and values whose names start with '_' can be set using {@link set_behaviour_var()}
* and {@link set_qt_var()}. There are some other methods like {@link has_behaviour_var()}
* to check wether a varaible with a particular name is set, and {@link get_behaviour_data()}
* to get all the behaviour data as an associative array.
* and values whose names start with '_' can be set using {@see set_behaviour_var()}
* and {@see set_qt_var()}. There are some other methods like {@see has_behaviour_var()}
* to check wether a varaible with a particular name is set, and {@see get_behaviour_data()}
* to get all the behaviour data as an associative array. There are also
* {@see get_metadata_var()}, {@see set_metadata_var()} and {@see has_metadata_var()},
*
* @copyright 2009 The Open University
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
Expand All @@ -71,7 +76,7 @@ class question_attempt_step {
private $id = null;

/**
* @var question_state one of the {@link question_state} constants.
* @var question_state one of the {@see question_state} constants.
* The state after this step.
*/
private $state;
Expand All @@ -91,16 +96,16 @@ class question_attempt_step {
/** @var array name => value pairs. The submitted data. */
private $data;

/** @var array name => array of {@link stored_file}s. Caches the contents of file areas. */
/** @var array name => array of {@see stored_file}s. Caches the contents of file areas. */
private $files = array();

/** @var stdClass User information. */
private $user = null;

/**
* You should not need to call this constructor in your own code. Steps are
* normally created by {@link question_attempt} methods like
* {@link question_attempt::process_action()}.
* normally created by {@see question_attempt} methods like
* {@see question_attempt::process_action()}.
* @param array $data the submitted data that defines this step.
* @param int $timestamp the time to record for the action. (If not given, use now.)
* @param int $userid the user to attribute the aciton to. (If not given, use the current user.)
Expand Down Expand Up @@ -147,7 +152,7 @@ public function get_state() {

/**
* Set the state. Normally only called by behaviours.
* @param question_state $state one of the {@link question_state} constants.
* @param question_state $state one of the {@see question_state} constants.
*/
public function set_state($state) {
$this->state = $state;
Expand Down Expand Up @@ -248,7 +253,8 @@ public function set_qt_var($name, $value) {
* type question_attempt::PARAM_FILES.
*
* @param string $name the name of the associated variable.
* @return array of {@link stored_files}.
* @param int $contextid contextid of the question attempt
* @return array of {@see stored_files}.
*/
public function get_qt_files($name, $contextid) {
if (array_key_exists($name, $this->files)) {
Expand Down Expand Up @@ -300,7 +306,7 @@ public function prepare_response_files_draft_itemid_with_text($name, $contextid,
/**
* Rewrite the @@PLUGINFILE@@ tokens in a response variable from this step
* that contains links to file. Normally you should probably call
* {@link question_attempt::rewrite_response_pluginfile_urls()} instead of
* {@see question_attempt::rewrite_response_pluginfile_urls()} instead of
* calling this method directly.
*
* @param string $text the text to update the URLs in.
Expand Down Expand Up @@ -379,7 +385,7 @@ public function get_behaviour_data() {
/**
* Get all the submitted data, but not the cached data. behaviour
* variables have the - at the start of their name. This is only really
* intended for use by {@link question_attempt::regrade()}, it should not
* intended for use by {@see question_attempt::regrade()}, it should not
* be considered part of the public API.
* @param array name => value pairs.
*/
Expand All @@ -397,7 +403,7 @@ public function get_submitted_data() {
/**
* Get all the data. behaviour variables have the - at the start of
* their name. This is only intended for internal use, for example by
* {@link question_engine_data_mapper::insert_question_attempt_step()},
* {@see question_engine_data_mapper::insert_question_attempt_step()},
* however, it can occasionally be useful in test code. It should not be
* considered part of the public API of this class.
* @param array name => value pairs.
Expand All @@ -410,7 +416,7 @@ public function get_all_data() {
* Set a metadata variable.
*
* Do not call this method directly from your code. It is for internal
* use only. You should call {@link question_usage::set_question_attempt_metadata()}.
* use only. You should call {@see question_usage::set_question_attempt_metadata()}.
*
* @param string $name the name of the variable to set. [a-z][a-z0-9]*.
* @param string $value the value to set.
Expand All @@ -423,7 +429,7 @@ public function set_metadata_var($name, $value) {
* Whether this step has a metadata variable.
*
* Do not call this method directly from your code. It is for internal
* use only. You should call {@link question_usage::get_question_attempt_metadata()}.
* use only. You should call {@see question_usage::get_question_attempt_metadata()}.
*
* @param string $name the name of the variable to set. [a-z][a-z0-9]*.
* @return bool the value to set previously, or null if this variable was never set.
Expand All @@ -436,7 +442,7 @@ public function has_metadata_var($name) {
* Get a metadata variable.
*
* Do not call this method directly from your code. It is for internal
* use only. You should call {@link question_usage::get_question_attempt_metadata()}.
* use only. You should call {@see question_usage::get_question_attempt_metadata()}.
*
* @param string $name the name of the variable to set. [a-z][a-z0-9]*.
* @return string the value to set previously, or null if this variable was never set.
Expand Down Expand Up @@ -510,10 +516,10 @@ public static function load_from_records($records, $attemptstepid, $qtype = null


/**
* A subclass of {@link question_attempt_step} used when processing a new submission.
* A subclass of {@see question_attempt_step} used when processing a new submission.
*
* When we are processing some new submitted data, which may or may not lead to
* a new step being added to the {@link question_usage_by_activity} we create an
* a new step being added to the {@see question_usage_by_activity} we create an
* instance of this class. which is then passed to the question behaviour and question
* type for processing. At the end of processing we then may, or may not, keep it.
*
Expand Down Expand Up @@ -583,7 +589,7 @@ public function variant_number_changed() {


/**
* A subclass of {@link question_attempt_step} that cannot be modified.
* A subclass of {@see question_attempt_step} that cannot be modified.
*
* @copyright 2009 The Open University
* @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
Expand All @@ -605,8 +611,8 @@ public function set_behaviour_var($name, $value) {


/**
* A null {@link question_attempt_step} returned from
* {@link question_attempt::get_last_step()} etc. when a an attempt has just been
* A null {@see question_attempt_step} returned from
* {@see question_attempt::get_last_step()} etc. when a an attempt has just been
* created and there is no actual step.
*
* @copyright 2009 The Open University
Expand All @@ -628,7 +634,7 @@ public function get_fraction() {


/**
* This is an adapter class that wraps a {@link question_attempt_step} and
* This is an adapter class that wraps a {@see question_attempt_step} and
* modifies the get/set_*_data methods so that they operate only on the parts
* that belong to a particular subquestion, as indicated by an extra prefix.
*
Expand Down Expand Up @@ -687,7 +693,7 @@ public function remove_prefix($field) {
* Filter some data to keep only those entries where the key contains
* extraprefix, and remove the extra prefix from the reutrned arrary.
* @param array $data some of the data stored in this step.
* @return array the data with the keys ajusted using {@link remove_prefix()}.
* @return array the data with the keys ajusted using {@see remove_prefix()}.
*/
public function filter_array($data) {
$result = array();
Expand Down

0 comments on commit 33e98af

Please sign in to comment.