From c6739acf7fd8f387c63dd929c0d3008253a0def4 Mon Sep 17 00:00:00 2001
From: Dan Marsden <dan@danmarsden.com>
Date: Tue, 2 May 2017 10:05:00 +1200
Subject: [PATCH] fix some phpdoc stuff.

---
 classes/sessions_page_params.php |  23 ++++
 classes/summary.php              |  22 ++--
 lib.php                          |  62 ++++++++--
 renderer.php                     | 194 ++++++++++++++++++++++++++++++-
 4 files changed, 280 insertions(+), 21 deletions(-)

diff --git a/classes/sessions_page_params.php b/classes/sessions_page_params.php
index aa5da8c..a638811 100644
--- a/classes/sessions_page_params.php
+++ b/classes/sessions_page_params.php
@@ -31,11 +31,34 @@ defined('MOODLE_INTERNAL') || die();
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class mod_attendance_sessions_page_params {
+    /**
+     *  Add Session.
+     */
     const ACTION_ADD               = 1;
+
+    /**
+     *  Update Session.
+     */
     const ACTION_UPDATE            = 2;
+
+    /**
+     * Delete Session
+     */
     const ACTION_DELETE            = 3;
+
+    /**
+     *  Delete selected Sessions.
+     */
     const ACTION_DELETE_SELECTED   = 4;
+
+    /**
+     *  Change duration of a session.
+     */
     const ACTION_CHANGE_DURATION   = 5;
+
+    /**
+     *  Delete a hidden session.
+     */
     const ACTION_DELETE_HIDDEN     = 6;
 
     /** @var int view mode of taking attendance page*/
diff --git a/classes/summary.php b/classes/summary.php
index 1001fb3..f177c88 100644
--- a/classes/summary.php
+++ b/classes/summary.php
@@ -14,6 +14,14 @@
 // You should have received a copy of the GNU General Public License
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
+/**
+ * Class that computes summary of users points
+ *
+ * @package   mod_attendance
+ * @copyright  2016 Antonio Carlos Mariani http://antonio.c.mariani@gmail.com
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ */
+
 defined('MOODLE_INTERNAL') || die();
 require_once($CFG->dirroot . '/mod/attendance/locallib.php');
 
@@ -47,8 +55,8 @@ class mod_attendance_summary {
     /**
      * Initializes the class
      *
-     * @param int attendance instance identifier
-     * @param array userids user instances identifier
+     * @param int $attendanceid instance identifier
+     * @param array $userids user instances identifier
      * @param int $startdate Attendance sessions startdate
      * @param int $enddate Attendance sessions enddate
      */
@@ -62,7 +70,7 @@ class mod_attendance_summary {
     /**
      * Returns true if the user has some session with points
      *
-     * @param int userid User instance id
+     * @param int $userid User instance id
      *
      * @return boolean
      */
@@ -106,7 +114,7 @@ class mod_attendance_summary {
     /**
      * Returns a summary of the points assigned to the user related to the taken sessions
      *
-     * @param int userid User instance id
+     * @param int $userid User instance id
      *
      * @return array
      */
@@ -135,7 +143,7 @@ class mod_attendance_summary {
     /**
      * Returns a summary of the points assigned to the user, both related to taken sessions and related to all sessions
      *
-     * @param int userid User instance id
+     * @param int $userid User instance id
      *
      * @return array
      */
@@ -172,7 +180,7 @@ class mod_attendance_summary {
     /**
      * Computes the summary of points for the users that have some taken session
      *
-     * @param array userids user instances identifier
+     * @param array $userids user instances identifier
      * @param int $startdate Attendance sessions startdate
      * @param int $enddate Attendance sessions enddate
      * @return  (userid, numtakensessions, points, maxpoints)
@@ -236,7 +244,7 @@ class mod_attendance_summary {
     /**
      * Computes the summary of taken sessions by acronym
      *
-     * @param array userids user instances identifier
+     * @param array $userids user instances identifier
      * @param int $startdate Attendance sessions startdate
      * @param int $enddate Attendance sessions enddate
      * @return  null
diff --git a/lib.php b/lib.php
index 0f44ca2..20416d2 100644
--- a/lib.php
+++ b/lib.php
@@ -54,6 +54,11 @@ function attendance_supports($feature) {
     }
 }
 
+/**
+ * Add default set of statuses to the new attendance.
+ *
+ * @param int $attid - id of attendance instance.
+ */
 function att_add_default_statuses($attid) {
     global $DB;
 
@@ -66,6 +71,12 @@ function att_add_default_statuses($attid) {
     $statuses->close();
 }
 
+/**
+ * Add new attendance instance.
+ *
+ * @param stdClass $attendance
+ * @return bool|int
+ */
 function attendance_add_instance($attendance) {
     global $DB;
 
@@ -80,7 +91,12 @@ function attendance_add_instance($attendance) {
     return $attendance->id;
 }
 
-
+/**
+ * Update existing attendance instance.
+ *
+ * @param stdClass $attendance
+ * @return bool
+ */
 function attendance_update_instance($attendance) {
     global $DB;
 
@@ -96,7 +112,12 @@ function attendance_update_instance($attendance) {
     return true;
 }
 
-
+/**
+ * Delete existing attendance
+ *
+ * @param int $id
+ * @return bool
+ */
 function attendance_delete_instance($id) {
     global $DB;
 
@@ -122,7 +143,7 @@ function attendance_delete_instance($id) {
 
 /**
  * Called by course/reset.php
- * @param $mform form passed by reference
+ * @param moodleform $mform form passed by reference
  */
 function attendance_reset_course_form_definition(&$mform) {
     $mform->addElement('header', 'attendanceheader', get_string('modulename', 'attendance'));
@@ -141,11 +162,20 @@ function attendance_reset_course_form_definition(&$mform) {
 
 /**
  * Course reset form defaults.
+ *
+ * @param stdClass $course
+ * @return array
  */
 function attendance_reset_course_form_defaults($course) {
     return array('reset_attendance_log' => 0, 'reset_attendance_statuses' => 0, 'reset_attendance_sessions' => 0);
 }
 
+/**
+ * Reset user data within attendance.
+ *
+ * @param stdClass $data
+ * @return array
+ */
 function attendance_reset_userdata($data) {
     global $DB;
 
@@ -198,12 +228,18 @@ function attendance_reset_userdata($data) {
 
     return $status;
 }
-/*
+/**
  * Return a small object with summary information about what a
  *  user has done with a given particular instance of this module
  *  Used for user activity reports.
  *  $return->time = the time they did it
  *  $return->info = a short text description
+ *
+ * @param stdClass $course - full course record.
+ * @param stdClass $user - full user record
+ * @param stdClass $mod
+ * @param stdClass $attendance
+ * @return stdClass.
  */
 function attendance_user_outline($course, $user, $mod, $attendance) {
     global $CFG;
@@ -229,10 +265,14 @@ function attendance_user_outline($course, $user, $mod, $attendance) {
 
     return $result;
 }
-/*
+/**
  * Print a detailed representation of what a  user has done with
  * a given particular instance of this module, for user activity reports.
  *
+ * @param stdClass $course
+ * @param stdClass $user
+ * @param stdClass $mod
+ * @param stdClass $attendance
  */
 function attendance_user_complete($course, $user, $mod, $attendance) {
     global $CFG;
@@ -245,14 +285,21 @@ function attendance_user_complete($course, $user, $mod, $attendance) {
     }
 }
 
+/**
+ * Dummy function - must exist to allow quick editing of module name.
+ *
+ * @param stdClass $attendance
+ * @param int $userid
+ * @param bool $nullifnone
+ */
 function attendance_update_grades($attendance, $userid=0, $nullifnone=true) {
     // We need this function to exist so that quick editing of module name is passed to gradebook.
 }
 /**
  * Create grade item for given attendance
  *
- * @param object $attendance object with extra cmidnumber
- * @param mixed optional array/object of grade(s); 'reset' means reset grades in gradebook
+ * @param stdClass $attendance object with extra cmidnumber
+ * @param mixed $grades optional array/object of grade(s); 'reset' means reset grades in gradebook
  * @return int 0 if ok, error code otherwise
  */
 function attendance_grade_item_update($attendance, $grades=null) {
@@ -390,7 +437,6 @@ function attendance_pluginfile($course, $cm, $context, $filearea, $args, $forced
  * Print tabs on attendance settings page.
  *
  * @param string $selected - current selected tab.
- *
  */
 function attendance_print_settings_tabs($selected = 'settings') {
     global $CFG;
diff --git a/renderer.php b/renderer.php
index 007225a..d1539ed 100644
--- a/renderer.php
+++ b/renderer.php
@@ -40,7 +40,7 @@ class mod_attendance_renderer extends plugin_renderer_base {
     /**
      * Renders tabs for attendance
      *
-     * @param atttabs - tabs to display
+     * @param attendance_tabs $atttabs - tabs to display
      * @return string html code
      */
     protected function render_attendance_tabs(attendance_tabs $atttabs) {
@@ -50,7 +50,7 @@ class mod_attendance_renderer extends plugin_renderer_base {
     /**
      * Renders filter controls for attendance
      *
-     * @param fcontrols - filter controls data to display
+     * @param attendance_filter_controls $fcontrols - filter controls data to display
      * @return string html code
      */
     protected function render_attendance_filter_controls(attendance_filter_controls $fcontrols) {
@@ -73,6 +73,12 @@ class mod_attendance_renderer extends plugin_renderer_base {
         return $o;
     }
 
+    /**
+     * Render group selector
+     *
+     * @param attendance_filter_controls $fcontrols
+     * @return mixed|string
+     */
     protected function render_sess_group_selector(attendance_filter_controls $fcontrols) {
         switch ($fcontrols->pageparams->selectortype) {
             case mod_attendance_page_with_filter_controls::SELECTOR_SESS_TYPE:
@@ -93,6 +99,12 @@ class mod_attendance_renderer extends plugin_renderer_base {
         return '';
     }
 
+    /**
+     * Render paging controls.
+     *
+     * @param attendance_filter_controls $fcontrols
+     * @return string
+     */
     protected function render_paging_controls(attendance_filter_controls $fcontrols) {
         $pagingcontrols = '';
 
@@ -127,6 +139,12 @@ class mod_attendance_renderer extends plugin_renderer_base {
         return $pagingcontrols;
     }
 
+    /**
+     * Render date controls.
+     *
+     * @param attendance_filter_controls $fcontrols
+     * @return string
+     */
     protected function render_curdate_controls(attendance_filter_controls $fcontrols) {
         global $CFG;
 
@@ -173,6 +191,12 @@ class mod_attendance_renderer extends plugin_renderer_base {
         return $curdatecontrols;
     }
 
+    /**
+     * Render view controls.
+     *
+     * @param attendance_filter_controls $fcontrols
+     * @return string
+     */
     protected function render_view_controls(attendance_filter_controls $fcontrols) {
         $views[ATT_VIEW_ALL] = get_string('all', 'attendance');
         $views[ATT_VIEW_ALLPAST] = get_string('allpast', 'attendance');
@@ -213,6 +237,12 @@ class mod_attendance_renderer extends plugin_renderer_base {
         return $o;
     }
 
+    /**
+     * Render session manage table.
+     *
+     * @param attendance_manage_data $sessdata
+     * @return string
+     */
     protected function render_sess_manage_table(attendance_manage_data $sessdata) {
         $this->page->requires->js_init_call('M.mod_attendance.init_manage');
 
@@ -261,6 +291,13 @@ class mod_attendance_renderer extends plugin_renderer_base {
         return html_writer::table($table);
     }
 
+    /**
+     * Construct date time actions.
+     *
+     * @param attendance_manage_data $sessdata
+     * @param stdClass $sess
+     * @return array
+     */
     private function construct_date_time_actions(attendance_manage_data $sessdata, $sess) {
         $actions = '';
 
@@ -300,6 +337,12 @@ class mod_attendance_renderer extends plugin_renderer_base {
         return array('date' => $date, 'time' => $time, 'actions' => $actions);
     }
 
+    /**
+     * Render session manage control.
+     *
+     * @param attendance_manage_data $sessdata
+     * @return string
+     */
     protected function render_sess_manage_control(attendance_manage_data $sessdata) {
         $table = new html_table();
         $table->attributes['class'] = ' ';
@@ -335,6 +378,12 @@ class mod_attendance_renderer extends plugin_renderer_base {
         return html_writer::table($table);
     }
 
+    /**
+     * Render take data.
+     *
+     * @param attendance_take_data $takedata
+     * @return string
+     */
     protected function render_attendance_take_data(attendance_take_data $takedata) {
         $controls = $this->render_attendance_take_controls($takedata);
         $table = html_writer::start_div('no-overflow');
@@ -373,6 +422,12 @@ class mod_attendance_renderer extends plugin_renderer_base {
         return $controls.$table.$statsoutput;
     }
 
+    /**
+     * Render take controls.
+     *
+     * @param attendance_take_data $takedata
+     * @return string
+     */
     protected function render_attendance_take_controls(attendance_take_data $takedata) {
         $table = new html_table();
         $table->attributes['class'] = ' ';
@@ -383,6 +438,12 @@ class mod_attendance_renderer extends plugin_renderer_base {
         return $this->output->container(html_writer::table($table), 'generalbox takecontrols');
     }
 
+    /**
+     * Construct take session info.
+     *
+     * @param attendance_take_data $takedata
+     * @return string
+     */
     private function construct_take_session_info(attendance_take_data $takedata) {
         $sess = $takedata->sessioninfo;
         $date = userdate($sess->sessdate, get_string('strftimedate'));
@@ -397,6 +458,12 @@ class mod_attendance_renderer extends plugin_renderer_base {
         return $sessinfo;
     }
 
+    /**
+     * Construct take controls.
+     *
+     * @param attendance_take_data $takedata
+     * @return string
+     */
     private function construct_take_controls(attendance_take_data $takedata) {
         global $CFG;
 
@@ -497,6 +564,12 @@ class mod_attendance_renderer extends plugin_renderer_base {
         return $controls;
     }
 
+    /**
+     * Render take list.
+     *
+     * @param attendance_take_data $takedata
+     * @return string
+     */
     protected function render_attendance_take_list(attendance_take_data $takedata) {
         global $PAGE, $CFG;
         $table = new html_table();
@@ -584,6 +657,12 @@ class mod_attendance_renderer extends plugin_renderer_base {
         return html_writer::table($table);
     }
 
+    /**
+     * Render take grid.
+     *
+     * @param attendance_take_data $takedata
+     * @return string
+     */
     protected function render_attendance_take_grid(attendance_take_data $takedata) {
         $table = new html_table();
         for ($i = 0; $i < $takedata->pageparams->gridcols; $i++) {
@@ -633,6 +712,12 @@ class mod_attendance_renderer extends plugin_renderer_base {
         return html_writer::table($table);
     }
 
+    /**
+     * Construct full name.
+     *
+     * @param stdClass $data
+     * @return string
+     */
     private function construct_fullname_head($data) {
         global $CFG;
 
@@ -659,6 +744,13 @@ class mod_attendance_renderer extends plugin_renderer_base {
         return $fullnamehead;
     }
 
+    /**
+     * Construct take user controls.
+     *
+     * @param attendance_take_data $takedata
+     * @param stdClass $user
+     * @return array
+     */
     private function construct_take_user_controls(attendance_take_data $takedata, $user) {
         $celldata = array();
         if ($user->enrolmentend and $user->enrolmentend < $takedata->sessioninfo->sessdate) {
@@ -713,6 +805,12 @@ class mod_attendance_renderer extends plugin_renderer_base {
         return $celldata;
     }
 
+    /**
+     * Render header.
+     *
+     * @param mod_attendance_header $header
+     * @return string
+     */
     protected function render_mod_attendance_header(mod_attendance_header $header) {
         if (!$header->should_render()) {
             return '';
@@ -730,6 +828,12 @@ class mod_attendance_renderer extends plugin_renderer_base {
         return $o;
     }
 
+    /**
+     * Render user data.
+     *
+     * @param attendance_user_data $userdata
+     * @return string
+     */
     protected function render_attendance_user_data(attendance_user_data $userdata) {
         $o = $this->render_user_report_tabs($userdata);
 
@@ -746,6 +850,12 @@ class mod_attendance_renderer extends plugin_renderer_base {
         return $o;
     }
 
+    /**
+     * Render user report tabs.
+     *
+     * @param attendance_user_data $userdata
+     * @return string
+     */
     protected function render_user_report_tabs(attendance_user_data $userdata) {
         $tabs = array();
 
@@ -763,6 +873,12 @@ class mod_attendance_renderer extends plugin_renderer_base {
         return print_tabs(array($tabs), $userdata->pageparams->mode, null, null, true);
     }
 
+    /**
+     * Construct user data.
+     *
+     * @param attendance_user_data $userdata
+     * @return string
+     */
     private function construct_user_data(attendance_user_data $userdata) {
         $o = html_writer::tag('h2', fullname($userdata->user));
 
@@ -796,6 +912,12 @@ class mod_attendance_renderer extends plugin_renderer_base {
         return $o;
     }
 
+    /**
+     * Construct user sessions log.
+     *
+     * @param attendance_user_data $userdata
+     * @return string
+     */
     private function construct_user_sessions_log(attendance_user_data $userdata) {
         $table = new html_table();
         $table->attributes['class'] = 'generaltable attwidth boxaligncenter';
@@ -869,12 +991,25 @@ class mod_attendance_renderer extends plugin_renderer_base {
         return html_writer::table($table);
     }
 
+    /**
+     * Construct time for display.
+     *
+     * @param int $datetime
+     * @param int $duration
+     * @return string
+     */
     private function construct_time($datetime, $duration) {
         $time = html_writer::tag('nobr', construct_session_time($datetime, $duration));
 
         return $time;
     }
 
+    /**
+     * Render report data.
+     *
+     * @param attendance_report_data $reportdata
+     * @return string
+     */
     protected function render_attendance_report_data(attendance_report_data $reportdata) {
         global $PAGE, $COURSE;
 
@@ -1314,7 +1449,7 @@ class mod_attendance_renderer extends plugin_renderer_base {
     /**
      * Build and return a html_table_cell for header rows
      *
-     * @param Mixed (html_table_cell or string) $cell the cell or a label for a cell
+     * @param html_table_cell|string $cell the cell or a label for a cell
      * @param boolean $contrast true menans the cell must be shown with bgcolor contrast
      * @param boolean $center true means the cell text should be centered. Othersiwe it should be left-aligned.
      * @param int $colspan how many columns should cell spans
@@ -1342,7 +1477,7 @@ class mod_attendance_renderer extends plugin_renderer_base {
     /**
      * Build and return a html_table_cell for data rows
      *
-     * @param Mixed (html_table_cell or string) $cell the cell or a label for a cell
+     * @param html_table_cell|string $cell the cell or a label for a cell
      * @param boolean $contrast true menans the cell must be shown with bgcolor contrast
      * @param boolean $center true means the cell text should be centered. Othersiwe it should be left-aligned.
      * @param int $colspan how many columns should cell spans
@@ -1370,7 +1505,7 @@ class mod_attendance_renderer extends plugin_renderer_base {
     /**
      * Build and return a html_table_cell for header or data rows
      *
-     * @param Mixed (html_table_cell or string) $cell the cell or a label for a cell
+     * @param html_table_cell|string $cell the cell or a label for a cell
      * @param Array $classes a list of css classes
      * @param int $colspan how many columns should cell spans
      * @param int $rowspan how many rows should cell spans
@@ -1431,6 +1566,12 @@ class mod_attendance_renderer extends plugin_renderer_base {
         return $this->output->url_select($opts, $selected, null);
     }
 
+    /**
+     * Render preferences data.
+     *
+     * @param stdClass $prefdata
+     * @return string
+     */
     protected function render_attendance_preferences_data($prefdata) {
         $this->page->requires->js('/mod/attendance/module.js');
 
@@ -1487,14 +1628,35 @@ class mod_attendance_renderer extends plugin_renderer_base {
         return $o;
     }
 
+    /**
+     * Render default statusset.
+     *
+     * @param attendance_default_statusset $prefdata
+     * @return string
+     */
     protected function render_attendance_default_statusset(attendance_default_statusset $prefdata) {
         return $this->render_attendance_preferences_data($prefdata);
     }
 
+    /**
+     * Render preferences data.
+     *
+     * @param stdClass $prefdata
+     * @return string
+     */
     protected function render_attendance_pref($prefdata) {
 
     }
 
+    /**
+     * Construct text input.
+     *
+     * @param string $name
+     * @param integer $size
+     * @param integer $maxlength
+     * @param string $value
+     * @return string
+     */
     private function construct_text_input($name, $size, $maxlength, $value='') {
         $attributes = array(
                 'type'      => 'text',
@@ -1505,6 +1667,13 @@ class mod_attendance_renderer extends plugin_renderer_base {
         return html_writer::empty_tag('input', $attributes);
     }
 
+    /**
+     * Construct action icons.
+     *
+     * @param stdClass $st
+     * @param stdClass $prefdata
+     * @return string
+     */
     private function construct_preferences_actions_icons($st, $prefdata) {
         global $OUTPUT;
         $params = array('sesskey' => sesskey(),
@@ -1532,6 +1701,13 @@ class mod_attendance_renderer extends plugin_renderer_base {
         return $showhideicon . $deleteicon;
     }
 
+    /**
+     * Construct preferences button.
+     *
+     * @param string $text
+     * @param string $action
+     * @return string
+     */
     private function construct_preferences_button($text, $action) {
         $attributes = array(
                 'type'      => 'submit',
@@ -1552,7 +1728,13 @@ class mod_attendance_renderer extends plugin_renderer_base {
         return html_writer::tag('p', $text, $attributes);
     }
 
-    // Show different picture if it is a temporary user.
+    /**
+     * Show different picture if it is a temporary user.
+     *
+     * @param stdClass $user
+     * @param array $opts
+     * @return string
+     */
     protected function user_picture($user, array $opts = null) {
         if ($user->type == 'temporary') {
             $attrib = array(