From c2d04204d887ea204f724f3cc03a7483d734ebf6 Mon Sep 17 00:00:00 2001
From: Dan Marsden <dan@danmarsden.com>
Date: Mon, 1 May 2017 14:39:06 +1200
Subject: [PATCH] Tidy up the classes/phpdocs a bit.

---
 export.php        |  68 +----------------------
 locallib.php      |  81 ++++++++++++++++++++++++++++
 renderhelpers.php | 135 +++++++++++++++++++++++++++++++++++++++++++---
 tempedit_form.php |  20 +++++++
 4 files changed, 232 insertions(+), 72 deletions(-)

diff --git a/export.php b/export.php
index beba01b..c940070 100644
--- a/export.php
+++ b/export.php
@@ -186,9 +186,9 @@ if ($formdata = $mform->get_data()) {
         }
 
         if ($formdata->format === 'text') {
-            exporttocsv($data, $filename);
+            attendance_exporttocsv($data, $filename);
         } else {
-            exporttotableed($data, $filename, $formdata->format);
+            attendance_exporttotableed($data, $filename, $formdata->format);
         }
         exit;
     } else {
@@ -207,68 +207,4 @@ $mform->display();
 echo $OUTPUT->footer();
 
 
-function exporttotableed($data, $filename, $format) {
-    global $CFG;
 
-    if ($format === 'excel') {
-        require_once("$CFG->libdir/excellib.class.php");
-        $filename .= ".xls";
-        $workbook = new MoodleExcelWorkbook("-");
-    } else {
-        require_once("$CFG->libdir/odslib.class.php");
-        $filename .= ".ods";
-        $workbook = new MoodleODSWorkbook("-");
-    }
-    // Sending HTTP headers.
-    $workbook->send($filename);
-    // Creating the first worksheet.
-    $myxls = $workbook->add_worksheet('Attendances');
-    // Format types.
-    $formatbc = $workbook->add_format();
-    $formatbc->set_bold(1);
-
-    $myxls->write(0, 0, get_string('course'), $formatbc);
-    $myxls->write(0, 1, $data->course);
-    $myxls->write(1, 0, get_string('group'), $formatbc);
-    $myxls->write(1, 1, $data->group);
-
-    $i = 3;
-    $j = 0;
-    foreach ($data->tabhead as $cell) {
-        // Merge cells if the heading would be empty (remarks column).
-        if (empty($cell)) {
-            $myxls->merge_cells($i, $j - 1, $i, $j);
-        } else {
-            $myxls->write($i, $j, $cell, $formatbc);
-        }
-        $j++;
-    }
-    $i++;
-    $j = 0;
-    foreach ($data->table as $row) {
-        foreach ($row as $cell) {
-            $myxls->write($i, $j++, $cell);
-        }
-        $i++;
-        $j = 0;
-    }
-    $workbook->close();
-}
-
-function exporttocsv($data, $filename) {
-    $filename .= ".txt";
-
-    header("Content-Type: application/download\n");
-    header("Content-Disposition: attachment; filename=\"$filename\"");
-    header("Expires: 0");
-    header("Cache-Control: must-revalidate,post-check=0,pre-check=0");
-    header("Pragma: public");
-
-    echo get_string('course')."\t".$data->course."\n";
-    echo get_string('group')."\t".$data->group."\n\n";
-
-    echo implode("\t", $data->tabhead)."\n";
-    foreach ($data->table as $row) {
-        echo implode("\t", $row)."\n";
-    }
-}
diff --git a/locallib.php b/locallib.php
index ccc5a96..d3265bf 100644
--- a/locallib.php
+++ b/locallib.php
@@ -399,4 +399,85 @@ function attendance_can_student_mark($sess) {
         }
     }
     return $canmark;
+}
+
+/**
+ * Generate worksheet for Attendance export
+ *
+ * @param stdclass $data The data for the report
+ * @param string $filename The name of the file
+ * @param string $format excel|ods
+ *
+ */
+function attendance_exporttotableed($data, $filename, $format) {
+    global $CFG;
+
+    if ($format === 'excel') {
+        require_once("$CFG->libdir/excellib.class.php");
+        $filename .= ".xls";
+        $workbook = new MoodleExcelWorkbook("-");
+    } else {
+        require_once("$CFG->libdir/odslib.class.php");
+        $filename .= ".ods";
+        $workbook = new MoodleODSWorkbook("-");
+    }
+    // Sending HTTP headers.
+    $workbook->send($filename);
+    // Creating the first worksheet.
+    $myxls = $workbook->add_worksheet('Attendances');
+    // Format types.
+    $formatbc = $workbook->add_format();
+    $formatbc->set_bold(1);
+
+    $myxls->write(0, 0, get_string('course'), $formatbc);
+    $myxls->write(0, 1, $data->course);
+    $myxls->write(1, 0, get_string('group'), $formatbc);
+    $myxls->write(1, 1, $data->group);
+
+    $i = 3;
+    $j = 0;
+    foreach ($data->tabhead as $cell) {
+        // Merge cells if the heading would be empty (remarks column).
+        if (empty($cell)) {
+            $myxls->merge_cells($i, $j - 1, $i, $j);
+        } else {
+            $myxls->write($i, $j, $cell, $formatbc);
+        }
+        $j++;
+    }
+    $i++;
+    $j = 0;
+    foreach ($data->table as $row) {
+        foreach ($row as $cell) {
+            $myxls->write($i, $j++, $cell);
+        }
+        $i++;
+        $j = 0;
+    }
+    $workbook->close();
+}
+
+/**
+ * Generate csv for Attendance export
+ *
+ * @param stdclass $data The data for the report
+ * @param string $filename The name of the file
+ *
+ */
+function attendance_exporttocsv($data, $filename) {
+    $filename .= ".txt";
+
+    header("Content-Type: application/download\n");
+    header("Content-Disposition: attachment; filename=\"$filename\"");
+    header("Expires: 0");
+    header("Cache-Control: must-revalidate,post-check=0,pre-check=0");
+    header("Pragma: public");
+
+    echo get_string('course')."\t".$data->course."\n";
+    echo get_string('group')."\t".$data->group."\n\n";
+
+    echo implode("\t", $data->tabhead)."\n";
+    foreach ($data->table as $row) {
+        echo implode("\t", $row)."\n";
+    }
 }
\ No newline at end of file
diff --git a/renderhelpers.php b/renderhelpers.php
index 285649c..8483963 100644
--- a/renderhelpers.php
+++ b/renderhelpers.php
@@ -33,18 +33,31 @@ require_once(dirname(__FILE__).'/renderables.php');
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class user_sessions_cells_generator {
+    /** @var array $cells - list of table cells. */
     protected $cells = array();
 
+    /** @var stdClass $reportdata - data for report. */
     protected $reportdata;
+
+    /** @var stdClass $user - user record. */
     protected $user;
 
+    /**
+     * Set up params.
+     * @param attendance_report_data $reportdata - reportdata.
+     * @param stdClass $user - user record.
+     */
     public function  __construct(attendance_report_data $reportdata, $user) {
         $this->reportdata = $reportdata;
         $this->user = $user;
     }
 
+    /**
+     * Get cells for the table.
+     *
+     * @param boolean $remarks - include remarks cell.
+     */
     public function get_cells($remarks = false) {
-        $this->init_cells();
         foreach ($this->reportdata->sessions as $sess) {
             if (array_key_exists($sess->id, $this->reportdata->sessionslog[$this->user->id]) &&
             !empty($this->reportdata->sessionslog[$this->user->id][$sess->id]->statusid)) {
@@ -88,34 +101,63 @@ class user_sessions_cells_generator {
         return $this->cells;
     }
 
-    protected function init_cells() {
-
-    }
-
+    /**
+     * Construct status cell.
+     *
+     * @param string $text - text for the cell.
+     */
     protected function construct_existing_status_cell($text) {
         $this->cells[] = $text;
     }
 
+    /**
+     * Construct hidden status cell.
+     *
+     * @param string $text - text for the cell.
+     */
     protected function construct_hidden_status_cell($text) {
         $this->cells[] = $text;
     }
 
+    /**
+     * Construct enrolments info cell.
+     *
+     * @param string $text - text for the cell.
+     */
     protected function construct_enrolments_info_cell($text) {
         $this->cells[] = $text;
     }
 
+    /**
+     * Construct not taken cell.
+     *
+     * @param string $text - text for the cell.
+     */
     protected function construct_not_taken_cell($text) {
         $this->cells[] = $text;
     }
 
+    /**
+     * Construct remarks cell.
+     *
+     * @param string $text - text for the cell.
+     */
     protected function construct_remarks_cell($text) {
         $this->cells[] = $text;
     }
 
+    /**
+     * Construct not existing user session cell.
+     *
+     * @param string $text - text for the cell.
+     */
     protected function construct_not_existing_for_user_session_cell($text) {
         $this->cells[] = $text;
     }
 
+    /**
+     * Dummy stub method, called at the end. - override if you need/
+     */
     protected function finalize_cells() {
     }
 }
@@ -127,17 +169,33 @@ class user_sessions_cells_generator {
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class user_sessions_cells_html_generator extends user_sessions_cells_generator {
+    /** @var html_table_cell $cell */
     private $cell;
 
+    /**
+     * Construct status cell.
+     *
+     * @param string $text - text for the cell.
+     */
     protected function construct_existing_status_cell($text) {
         $this->close_open_cell_if_needed();
         $this->cells[] = html_writer::span($text, 'attendancestatus-'.$text);
     }
 
+    /**
+     * Construct hidden status cell.
+     *
+     * @param string $text - text for the cell.
+     */
     protected function construct_hidden_status_cell($text) {
         $this->cells[] = html_writer::tag('s', $text);
     }
 
+    /**
+     * Construct enrolments info cell.
+     *
+     * @param string $text - text for the cell.
+     */
     protected function construct_enrolments_info_cell($text) {
         if (is_null($this->cell)) {
             $this->cell = new html_table_cell($text);
@@ -153,6 +211,9 @@ class user_sessions_cells_html_generator extends user_sessions_cells_generator {
         }
     }
 
+    /**
+     * Close cell if needed.
+     */
     private function close_open_cell_if_needed() {
         if ($this->cell) {
             $this->cells[] = $this->cell;
@@ -160,11 +221,21 @@ class user_sessions_cells_html_generator extends user_sessions_cells_generator {
         }
     }
 
+    /**
+     * Construct not taken cell.
+     *
+     * @param string $text - text for the cell.
+     */
     protected function construct_not_taken_cell($text) {
         $this->close_open_cell_if_needed();
         $this->cells[] = $text;
     }
 
+    /**
+     * Construct remarks cell.
+     *
+     * @param string $text - text for the cell.
+     */
     protected function construct_remarks_cell($text) {
         global $OUTPUT;
 
@@ -183,11 +254,20 @@ class user_sessions_cells_html_generator extends user_sessions_cells_generator {
         $this->cells[] = $markcell;
     }
 
+    /**
+     * Construct not existing for user session cell.
+     *
+     * @param string $text - text for the cell.
+     */
     protected function construct_not_existing_for_user_session_cell($text) {
         $this->close_open_cell_if_needed();
         $this->cells[] = $text;
     }
 
+    /**
+     * Finalize cells.
+     *
+     */
     protected function finalize_cells() {
         if ($this->cell) {
             $this->cells[] = $this->cell;
@@ -202,12 +282,23 @@ class user_sessions_cells_html_generator extends user_sessions_cells_generator {
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class user_sessions_cells_text_generator extends user_sessions_cells_generator {
+    /** @var string $enrolmentsinfocelltext. */
     private $enrolmentsinfocelltext;
 
+    /**
+     * Construct hidden status cell.
+     *
+     * @param string $text - text for the cell.
+     */
     protected function construct_hidden_status_cell($text) {
         $this->cells[] = '-'.$text;
     }
 
+    /**
+     * Construct enrolments info cell.
+     *
+     * @param string $text - text for the cell.
+     */
     protected function construct_enrolments_info_cell($text) {
         if ($this->enrolmentsinfocelltext != $text) {
             $this->enrolmentsinfocelltext = $text;
@@ -218,7 +309,11 @@ class user_sessions_cells_text_generator extends user_sessions_cells_generator {
     }
 }
 
-// Used to print simple time - 1am instead of 1:00am.
+/**
+ * Used to print simple time - 1am instead of 1:00am.
+ *
+ * @param int $time - unix timestamp.
+ */
 function attendance_strftimehm($time) {
     $mins = userdate($time, '%M');
     if ($mins == '00') {
@@ -228,6 +323,12 @@ function attendance_strftimehm($time) {
     }
 }
 
+/**
+ * Used to print simple time - 1am instead of 1:00am.
+ *
+ * @param int $datetime - unix timestamp.
+ * @param int $duration - number of seconds.
+ */
 function construct_session_time($datetime, $duration) {
     $starttime = attendance_strftimehm($datetime);
     $endtime = attendance_strftimehm($datetime + $duration);
@@ -235,6 +336,13 @@ function construct_session_time($datetime, $duration) {
     return $starttime . ($duration > 0 ? ' - ' . $endtime : '');
 }
 
+/**
+ * Used to print session time.
+ *
+ * @param int $datetime - unix timestamp.
+ * @param int $duration - number of seconds duration.
+ * @return string.
+ */
 function construct_session_full_date_time($datetime, $duration) {
     $sessinfo = userdate($datetime, get_string('strftimedmyw', 'attendance'));
     $sessinfo .= ' '.construct_session_time($datetime, $duration);
@@ -242,6 +350,13 @@ function construct_session_full_date_time($datetime, $duration) {
     return $sessinfo;
 }
 
+/**
+ * Used to construct user summary.
+ *
+ * @param stdclass $usersummary - data for summary.
+ * @param int $view - ATT_VIEW_ALL|ATT_VIEW_
+ * @return string.
+ */
 function construct_user_data_stat($usersummary, $view) {
     $stattable = new html_table();
     $stattable->attributes['class'] = 'attlist';
@@ -301,6 +416,14 @@ function construct_user_data_stat($usersummary, $view) {
     return html_writer::table($stattable);
 }
 
+/**
+ * Returns html user summary
+ *
+ * @param stdclass $attendance - attendance record.
+ * @param stdclass $user - user record
+ * @return string.
+ *
+ */
 function construct_full_user_stat_html_table($attendance, $user) {
     $summary = new mod_attendance_summary($attendance->id, $user->id);
     return construct_user_data_stat($summary->get_all_sessions_summary_for($user->id), ATT_VIEW_ALL);
diff --git a/tempedit_form.php b/tempedit_form.php
index 0376eb1..ef4d79b 100644
--- a/tempedit_form.php
+++ b/tempedit_form.php
@@ -27,8 +27,19 @@ defined('MOODLE_INTERNAL') || die();
 global $CFG;
 require_once($CFG->libdir.'/formslib.php');
 
+/**
+ * class for displaying tempedit form.
+ *
+ * @copyright  2013 Davo Smith, Synergy Learning
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
 class tempedit_form extends moodleform {
 
+    /**
+     * Called to define this moodle form
+     *
+     * @return void
+     */
     public function definition() {
 
         $mform = $this->_form;
@@ -55,11 +66,20 @@ class tempedit_form extends moodleform {
         $mform->closeHeaderBefore('submit');
     }
 
+    /**
+     * Apply filter to form
+     *
+     */
     public function definition_after_data() {
         $mform = $this->_form;
         $mform->applyFilter('tname', 'trim');
     }
 
+    /**
+     * Perform validation on the form
+     * @param array $data
+     * @param array $files
+     */
     public function validation($data, $files) {
         $errors = parent::validation($data, $files);