diff --git a/question/engine/questionattemptstep.php b/question/engine/questionattemptstep.php index 781aeb053dd..f8bddf68507 100644 --- a/question/engine/questionattemptstep.php +++ b/question/engine/questionattemptstep.php @@ -28,10 +28,10 @@ defined('MOODLE_INTERNAL') || die(); /** - * 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. * @@ -39,8 +39,7 @@ defined('MOODLE_INTERNAL') || die(); * 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 @@ -50,15 +49,21 @@ defined('MOODLE_INTERNAL') || die(); * 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 @@ -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; @@ -91,7 +96,7 @@ 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. */ @@ -99,8 +104,8 @@ class question_attempt_step { /** * 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.) @@ -147,7 +152,7 @@ class question_attempt_step { /** * 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; @@ -249,7 +254,7 @@ class question_attempt_step { * * @param string $name the name of the associated variable. * @param int $contextid contextid of the question attempt - * @return array of {@link stored_files}. + * @return array of {@see stored_files}. */ public function get_qt_files($name, $contextid) { if (array_key_exists($name, $this->files)) { @@ -303,7 +308,7 @@ class question_attempt_step { /** * 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. @@ -383,7 +388,7 @@ class question_attempt_step { /** * 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. */ @@ -401,7 +406,7 @@ class question_attempt_step { /** * 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. @@ -414,7 +419,7 @@ class question_attempt_step { * 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. @@ -427,7 +432,7 @@ class question_attempt_step { * 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. @@ -440,7 +445,7 @@ class question_attempt_step { * 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. @@ -514,10 +519,10 @@ class question_attempt_step { /** - * 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. * @@ -587,7 +592,7 @@ class question_attempt_pending_step extends question_attempt_step { /** - * 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 @@ -609,8 +614,8 @@ class question_attempt_step_read_only extends question_attempt_step { /** - * 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 @@ -632,7 +637,7 @@ class question_null_step { /** - * 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. * @@ -691,7 +696,7 @@ class question_attempt_step_subquestion_adapter extends question_attempt_step { * 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();