From bc113f89cca67e3dec5334e7d7c55fc3e5ca53e8 Mon Sep 17 00:00:00 2001 From: Tim Hunt Date: Sun, 5 Apr 2020 13:27:17 +0100 Subject: [PATCH] MDL-66259 qtypes: Add missing comment on get_random_guess_score A bit off-topic for this issue number, but I noticed it while working on this, and though it was not worth creating a separate MDL for. --- question/type/questiontypebase.php | 22 ++++++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/question/type/questiontypebase.php b/question/type/questiontypebase.php index d8f80435c78..c2fe4e93d52 100644 --- a/question/type/questiontypebase.php +++ b/question/type/questiontypebase.php @@ -1055,9 +1055,27 @@ class question_type { } /** - * @param object $question + * Calculate the score a monkey would get on a question by clicking randomly. + * + * Some question types have significant non-zero average expected score + * of the response is just selected randomly. For example 50% for a + * true-false question. It is useful to know what this is. For example + * it gets shown in the quiz statistics report. + * + * For almost any open-ended question type (E.g. shortanswer or numerical) + * this should be 0. + * + * For selective response question types (e.g. multiple choice), you can probably compute this. + * + * For particularly complicated question types the may be impossible or very + * difficult to compute. In this case return null. (Or, if the expected score + * is very tiny even though the exact value is unknown, it may appropriate + * to return 0.) + * + * @param stdClass $questiondata data defining a question, as returned by + * question_bank::load_question_data(). * @return number|null either a fraction estimating what the student would - * score by guessing, or null, if it is not possible to estimate. + * score by guessing, or null, if it is not possible to estimate. */ public function get_random_guess_score($questiondata) { return 0;