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.

diff --git a/question/type/questiontypebase.php b/question/type/questiontypebase.php
index d8f8043..c2fe4e9 100644 (file)
--- 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;