From 522bef80308581b4cd9835cdd94219f444c35ea0 Mon Sep 17 00:00:00 2001
From: Jamie Pratt <me@jamiep.org>
Date: Wed, 25 Sep 2013 12:22:41 +0700
Subject: [PATCH] MDL-41888 More comments

---
 .../report/statistics/classes/calculated.php  | 31 +++++++++-------
 .../report/statistics/classes/calculator.php  | 36 ++++++++++++-------
 2 files changed, 43 insertions(+), 24 deletions(-)

diff --git a/mod/quiz/report/statistics/classes/calculated.php b/mod/quiz/report/statistics/classes/calculated.php
index 302b0074a23..40a62107e72 100644
--- a/mod/quiz/report/statistics/classes/calculated.php
+++ b/mod/quiz/report/statistics/classes/calculated.php
@@ -17,6 +17,10 @@
 /**
  * The statistics calculator returns an instance of this class which contains the calculated statistics.
  *
+ * These quiz statistics calculations are described here :
+ *
+ * http://docs.moodle.org/dev/Quiz_statistics_calculations#Test_statistics
+ *
  * @package    quiz_statistics
  * @copyright  2013 The Open University
  * @author     James Pratt me@jamiep.org
@@ -35,6 +39,8 @@ class quiz_statistics_calculated {
      */
     public $allattempts;
 
+    /* Following stats all described here : http://docs.moodle.org/dev/Quiz_statistics_calculations#Test_statistics  */
+
     public $firstattemptscount = 0;
 
     public $allattemptscount = 0;
@@ -43,10 +49,6 @@ class quiz_statistics_calculated {
 
     public $allattemptsavg;
 
-    public $firstattemptstotal = 0;
-
-    public $allattemptstotal = 0;
-
     public $median;
 
     public $standarddeviation;
@@ -61,6 +63,9 @@ class quiz_statistics_calculated {
 
     public $standarderror;
 
+    /**
+     * @var int time these stats where calculated and cached.
+     */
     public $timemodified;
 
     public function s() {
@@ -79,14 +84,6 @@ class quiz_statistics_calculated {
         }
     }
 
-    public function total() {
-        if ($this->allattempts) {
-            return $this->allattemptstotal;
-        } else {
-            return $this->firstattemptstotal;
-        }
-    }
-
     /**
      * @param $course
      * @param $cm
@@ -170,11 +167,16 @@ class quiz_statistics_calculated {
     }
 
 
+    /**
+     * @var array of names of properties of this class that are cached in db record.
+     */
     protected $fieldsindb = array('allattempts', 'firstattemptscount', 'allattemptscount', 'firstattemptsavg', 'allattemptsavg',
                                     'median', 'standarddeviation', 'skewness',
                                     'kurtosis', 'cic', 'errorratio', 'standarderror');
 
     /**
+     * Cache the stats contained in this class.
+     *
      * @param $qubaids qubaid_condition
      */
     public function cache($qubaids) {
@@ -202,6 +204,11 @@ class quiz_statistics_calculated {
 
     }
 
+    /**
+     * Given a record from 'quiz_statistics' table load the data into the properties of this class.
+     *
+     * @param $record from db.
+     */
     public function populate_from_record($record) {
         foreach ($this->fieldsindb as $field) {
             $this->$field = $record->$field;
diff --git a/mod/quiz/report/statistics/classes/calculator.php b/mod/quiz/report/statistics/classes/calculator.php
index cbe6a761bb8..6a0d6b8ac25 100644
--- a/mod/quiz/report/statistics/classes/calculator.php
+++ b/mod/quiz/report/statistics/classes/calculator.php
@@ -17,6 +17,10 @@
 /**
  * Class to calculate and also manage caching of quiz statistics.
  *
+ * These quiz statistics calculations are described here :
+ *
+ * http://docs.moodle.org/dev/Quiz_statistics_calculations#Test_statistics
+ *
  * @package    quiz_statistics
  * @copyright  2013 The Open University
  * @author     James Pratt me@jamiep.org
@@ -39,7 +43,7 @@ class quiz_statistics_calculator {
      */
     public function calculate($quizid, $currentgroup, $useallattempts, $groupstudents, $p, $sumofmarkvariance) {
 
-        $quizstats = $this->attempt_counts_totals_and_averages($quizid, $currentgroup, $useallattempts, $groupstudents);
+        $quizstats = $this->attempt_counts_and_averages($quizid, $currentgroup, $useallattempts, $groupstudents);
 
         $s = $quizstats->s();
 
@@ -129,20 +133,21 @@ class quiz_statistics_calculator {
     }
 
     /**
+     * Calculating count and mean of marks for first and ALL attempts by students.
+     *
+     * See : http://docs.moodle.org/dev/Quiz_item_analysis_calculations_in_practise
+     *                                      #Calculating_MEAN_of_grades_for_all_attempts_by_students
      * @param int $quizid
      * @param int $currentgroup
      * @param bool $useallattempts
      * @param array $groupstudents
      * @return quiz_statistics_calculated containing calculated counts, totals and averages.
      */
-    protected function attempt_counts_totals_and_averages($quizid, $currentgroup, $useallattempts, $groupstudents) {
+    protected function attempt_counts_and_averages($quizid, $currentgroup, $useallattempts, $groupstudents) {
         global $DB;
 
         $quizstats = new quiz_statistics_calculated($useallattempts);
 
-        // Calculating MEAN of marks for ALL attempts by students
-        // http://docs.moodle.org/dev/Quiz_item_analysis_calculations_in_practise
-        //     #Calculating_MEAN_of_grades_for_all_attempts_by_students.
         list($fromqa, $whereqa, $qaparams) = quiz_statistics_attempts_sql($quizid, $currentgroup, $groupstudents, true);
 
         $attempttotals = $DB->get_records_sql("
@@ -155,36 +160,40 @@ class quiz_statistics_calculator {
                 GROUP BY CASE WHEN attempt = 1 THEN 1 ELSE 0 END", $qaparams);
 
         // Above query that returns sums and counts for first attempt and other non first attempts.
-        // We want to work out stats for first attempt or all attempts.
+        // We want to work out stats for first attempt or ALL attempts.
 
         if (isset($attempttotals[1])) {
             $quizstats->firstattemptscount = $attempttotals[1]->countrecs;
-            $quizstats->firstattemptstotal = $attempttotals[1]->total;
+            $firstattemptstotal = $attempttotals[1]->total;
         } else {
             $quizstats->firstattemptscount = 0;
-            $quizstats->firstattemptstotal = 0;
+            $firstattemptstotal = 0;
         }
 
         if (isset($attempttotals[0])) {
             $quizstats->allattemptscount = $quizstats->firstattemptscount + $attempttotals[0]->countrecs;
-            $quizstats->allattemptstotal = $quizstats->firstattemptstotal + $attempttotals[0]->total;
+            $allattemptstotal = $firstattemptstotal + $attempttotals[0]->total;
         } else {
             $quizstats->allattemptscount = $quizstats->firstattemptscount;
-            $quizstats->allattemptstotal = $quizstats->firstattemptstotal;
+            $allattemptstotal = $firstattemptstotal;
         }
 
         if ($quizstats->allattemptscount !== 0) {
-            $quizstats->allattemptsavg = $quizstats->allattemptstotal / $quizstats->allattemptscount;
+            $quizstats->allattemptsavg = $allattemptstotal / $quizstats->allattemptscount;
         }
 
         if ($quizstats->firstattemptscount !== 0) {
-            $quizstats->firstattemptsavg = $quizstats->firstattemptstotal / $quizstats->firstattemptscount;
+            $quizstats->firstattemptsavg = $firstattemptstotal / $quizstats->firstattemptscount;
         }
 
         return $quizstats;
     }
 
     /**
+     * Median mark.
+     *
+     * http://docs.moodle.org/dev/Quiz_statistics_calculations#Median_Score
+     *
      * @param $s integer count of attempts
      * @param $fromqa string
      * @param $whereqa string
@@ -215,6 +224,9 @@ class quiz_statistics_calculator {
     /**
      * Fetch the sum of squared, cubed and to the power 4 differences between sumgrade and it's mean.
      *
+     * Explanation here : http://docs.moodle.org/dev/Quiz_item_analysis_calculations_in_practise
+     *              #Calculating_Standard_Deviation.2C_Skewness_and_Kurtosis_of_grades_for_all_attempts_by_students
+     *
      * @param $mean
      * @param $fromqa
      * @param $whereqa