From 2ebcd2c17e1306a0c762024f35e0c0c808176da0 Mon Sep 17 00:00:00 2001 From: Dan Marsden Date: Thu, 4 Jul 2013 13:53:18 +1200 Subject: [PATCH] More coding guideline stuff - phpdocs. --- add_form.php | 16 +++++++ ...backup_attendance_activity_task.class.php} | 8 +++- ...lib.php => backup_attendance_stepslib.php} | 11 ++++- .../backup_attforblock_settingslib.php | 26 ------------ ...estore_attendance_activity_task.class.php} | 11 +++-- ...ib.php => restore_attendance_stepslib.php} | 42 ++++++++++++++++--- db/access.php | 37 ++++------------ db/install.php | 7 +--- db/upgrade.php | 16 +++++-- duration_form.php | 11 +++++ export_form.php | 14 ++++++- lang/en/attendance.php | 8 ++++ lib.php | 3 +- locallib.php | 3 +- mod_form.php | 15 +++++-- renderables.php | 5 +++ renderer.php | 1 + renderhelpers.php | 17 +++++++- sessions.php | 3 +- update_form.php | 14 ++++++- 20 files changed, 178 insertions(+), 90 deletions(-) rename backup/moodle2/{backup_attforblock_activity_task.class.php => backup_attendance_activity_task.class.php} (91%) rename backup/moodle2/{backup_attforblock_stepslib.php => backup_attendance_stepslib.php} (92%) delete mode 100644 backup/moodle2/backup_attforblock_settingslib.php rename backup/moodle2/{restore_attforblock_activity_task.class.php => restore_attendance_activity_task.class.php} (89%) rename backup/moodle2/{restore_attforblock_stepslib.php => restore_attendance_stepslib.php} (83%) diff --git a/add_form.php b/add_form.php index baab1d3..4a96ca8 100644 --- a/add_form.php +++ b/add_form.php @@ -24,8 +24,19 @@ require_once($CFG->libdir.'/formslib.php'); +/** + * class for displaying add form. + * + * @copyright 2011 Artem Andreev + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ class mod_attendance_add_form extends moodleform { + /** + * Called to define this moodle form + * + * @return void + */ public function definition() { global $CFG, $USER; @@ -139,6 +150,11 @@ class mod_attendance_add_form extends moodleform { $this->add_action_buttons(false, $submit_string); } + /** + * Perform minimal validation on the settings form + * @param array $data + * @param array $files + */ public function validation($data, $files) { $errors = parent::validation($data, $files); diff --git a/backup/moodle2/backup_attforblock_activity_task.class.php b/backup/moodle2/backup_attendance_activity_task.class.php similarity index 91% rename from backup/moodle2/backup_attforblock_activity_task.class.php rename to backup/moodle2/backup_attendance_activity_task.class.php index b7c2094..810c7da 100644 --- a/backup/moodle2/backup_attforblock_activity_task.class.php +++ b/backup/moodle2/backup_attendance_activity_task.class.php @@ -17,8 +17,7 @@ /** * Class {@link backup_attendance_activity_task} definition * - * @package mod - * @subpackage attendance + * @package mod_attendance * @copyright 2011 Artem Andreev * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ @@ -30,6 +29,9 @@ require_once($CFG->dirroot . '/mod/attendance/backup/moodle2/backup_attendance_s /** * Provides all the settings and steps to perform one complete backup of attendance activity + * + * @copyright 2011 Artem Andreev + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class backup_attendance_activity_task extends backup_activity_task { @@ -49,6 +51,8 @@ class backup_attendance_activity_task extends backup_activity_task { /** * Code the transformations to perform in the activity in * order to get transportable (encoded) links + * @param string $content + * @return string */ static public function encode_content_links($content) { global $CFG; diff --git a/backup/moodle2/backup_attforblock_stepslib.php b/backup/moodle2/backup_attendance_stepslib.php similarity index 92% rename from backup/moodle2/backup_attforblock_stepslib.php rename to backup/moodle2/backup_attendance_stepslib.php index c09ac38..877f6e8 100644 --- a/backup/moodle2/backup_attforblock_stepslib.php +++ b/backup/moodle2/backup_attendance_stepslib.php @@ -17,8 +17,7 @@ /** * Defines all the backup steps that will be used by {@link backup_attendance_activity_task} * - * @package mod - * @subpackage attendance + * @package mod_attendance * @copyright 2011 Artem Andreev * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ @@ -27,9 +26,17 @@ defined('MOODLE_INTERNAL') || die(); /** * Defines the complete attendance structure for backup, with file and id annotations + * + * @copyright 2011 Artem Andreev + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class backup_attendance_activity_structure_step extends backup_activity_structure_step { + /** + * Define the structure of the backup workflow. + * + * @return restore_path_element $structure + */ protected function define_structure() { // Are we including userinfo? diff --git a/backup/moodle2/backup_attforblock_settingslib.php b/backup/moodle2/backup_attforblock_settingslib.php deleted file mode 100644 index 26cb3ba..0000000 --- a/backup/moodle2/backup_attforblock_settingslib.php +++ /dev/null @@ -1,26 +0,0 @@ -. - -/** - * @package mod - * @subpackage attendance - * @copyright 2011 Artem Andreev - * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later - */ - - // This activity has not particular settings but the inherited from the generic - // backup_activity_task so here there isn't any class definition, like the ones - // existing in /backup/moodle2/backup_settingslib.php (activities section). diff --git a/backup/moodle2/restore_attforblock_activity_task.class.php b/backup/moodle2/restore_attendance_activity_task.class.php similarity index 89% rename from backup/moodle2/restore_attforblock_activity_task.class.php rename to backup/moodle2/restore_attendance_activity_task.class.php index 972e10f..5ca7794 100644 --- a/backup/moodle2/restore_attforblock_activity_task.class.php +++ b/backup/moodle2/restore_attendance_activity_task.class.php @@ -15,8 +15,9 @@ // along with Moodle. If not, see . /** - * @package mod - * @subpackage attendance + * Define all the restore steps that will be used by the restore_attendance_activity_task + * + * @package mod_attendance * @copyright 2011 Artem Andreev * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ @@ -26,8 +27,10 @@ defined('MOODLE_INTERNAL') || die(); require_once($CFG->dirroot . '/mod/attendance/backup/moodle2/restore_attendance_stepslib.php'); /** - * attendance restore task that provides all the settings and steps to perform one - * complete restore of the activity + * Attendance restore task that provides all the settings and steps to perform one complete restore of the activity + * + * @copyright 2011 Artem Andreev + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class restore_attendance_activity_task extends restore_activity_task { diff --git a/backup/moodle2/restore_attforblock_stepslib.php b/backup/moodle2/restore_attendance_stepslib.php similarity index 83% rename from backup/moodle2/restore_attforblock_stepslib.php rename to backup/moodle2/restore_attendance_stepslib.php index 2a9c461..b177fb5 100644 --- a/backup/moodle2/restore_attforblock_stepslib.php +++ b/backup/moodle2/restore_attendance_stepslib.php @@ -15,8 +15,9 @@ // along with Moodle. If not, see . /** - * @package mod - * @subpackage attendance + * Structure step to restore one attendance activity + * + * @package mod_attendance * @copyright 2011 Artem Andreev * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ @@ -25,13 +26,17 @@ defined('MOODLE_INTERNAL') || die(); /** * Define all the restore steps that will be used by the restore_attendance_activity_task - */ - -/** - * Structure step to restore one attendance activity + * + * @copyright 2011 Artem Andreev + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class restore_attendance_activity_structure_step extends restore_activity_structure_step { + /** + * Define the structure of the restore workflow. + * + * @return restore_path_element $structure + */ protected function define_structure() { $paths = array(); @@ -60,6 +65,12 @@ class restore_attendance_activity_structure_step extends restore_activity_struct return $this->prepare_activity_structure($paths); } + /** + * Process an attendance restore. + * + * @param object $data The data in object form + * @return void + */ protected function process_attendance($data) { global $DB; @@ -73,6 +84,11 @@ class restore_attendance_activity_structure_step extends restore_activity_struct $this->apply_activity_instance($newitemid); } + /** + * Process attendance status restore + * @param object $data The data in object form + * @return void + */ protected function process_attendance_status($data) { global $DB; @@ -85,6 +101,11 @@ class restore_attendance_activity_structure_step extends restore_activity_struct $this->set_mapping('attendance_status', $oldid, $newitemid); } + /** + * Process attendance session restore + * @param object $data The data in object form + * @return void + */ protected function process_attendance_session($data) { global $DB; @@ -102,6 +123,11 @@ class restore_attendance_activity_structure_step extends restore_activity_struct $this->set_mapping('attendance_session', $oldid, $newitemid, true); } + /** + * Process attendance log restore + * @param object $data The data in object form + * @return void + */ protected function process_attendance_log($data) { global $DB; @@ -122,6 +148,10 @@ class restore_attendance_activity_structure_step extends restore_activity_struct $newitemid = $DB->insert_record('attendance_log', $data); } + /** + * Once the database tables have been fully restored, restore the files + * @return void + */ protected function after_execute() { $this->add_related_files('mod_attendance', 'session', 'attendance_session'); } diff --git a/db/access.php b/db/access.php index 02bbba3..90ae65a 100644 --- a/db/access.php +++ b/db/access.php @@ -14,36 +14,13 @@ // You should have received a copy of the GNU General Public License // along with Moodle. If not, see . -// -// Capability definitions for the assignment module. -// -// The capabilities are loaded into the database table when the module is -// installed or updated. Whenever the capability definitions are updated, -// the module version number should be bumped up. -// -// The system has four possible values for a capability: -// CAP_ALLOW, CAP_PREVENT, CAP_PROHIBIT, and inherit (not set). -// -// -// CAPABILITY NAMING CONVENTION -// -// It is important that capability names are unique. The naming convention -// for capabilities that are specific to modules and blocks is as follows: -// [mod/block]/: -// -// component_name should be the same as the directory name of the mod or block. -// -// Core moodle capabilities are defined thus: -// moodle/: -// -// Examples: mod/forum:viewpost -// block/recent_activity:view -// moodle/site:deleteuser -// -// The variable name for the capability definitions array follows the format -// $__capabilities -// -// For the core capabilities, the variable is $moodle_capabilities. +/** + * Capability definitions for this module. + * + * @package mod_attendance + * @copyright 2011 Artem Andreev + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ $capabilities = array( diff --git a/db/install.php b/db/install.php index b6c668e..968152c 100644 --- a/db/install.php +++ b/db/install.php @@ -14,13 +14,10 @@ // You should have received a copy of the GNU General Public License // along with Moodle. If not, see . - /** - * This file replaces the legacy STATEMENTS section in db/install.xml, - * lib.php/modulename_install() post installation hook and partially defaults.php + * post installation hook for adding data. * - * @package mod - * @subpackage attendance + * @package mod_attendance * @copyright 2011 Artem Andreev * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ diff --git a/db/upgrade.php b/db/upgrade.php index 9a48c77..0e9336d 100644 --- a/db/upgrade.php +++ b/db/upgrade.php @@ -14,9 +14,19 @@ // You should have received a copy of the GNU General Public License // along with Moodle. If not, see . -// This file keeps track of upgrades to -// the attendance module. +/** + * upgrade processes for this module. + * + * @package mod_attendance + * @copyright 2011 Artem Andreev + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ +/** + * upgrade this attendance instance - this function could be skipped but it will be needed later + * @param int $oldversion The old version of the attendance module + * @return bool + */ function xmldb_attendance_upgrade($oldversion=0) { global $CFG, $THEME, $DB; @@ -24,6 +34,6 @@ function xmldb_attendance_upgrade($oldversion=0) { $result = true; - // UPGRADES from attforblock are only supported for sites that are running attforblock version 2012120700 + // UPGRADES from attforblock are only supported for sites that are running attforblock version 2012120700. return $result; } diff --git a/duration_form.php b/duration_form.php index b8ab908..92877ba 100644 --- a/duration_form.php +++ b/duration_form.php @@ -24,8 +24,19 @@ require_once($CFG->libdir.'/formslib.php'); +/** + * class for displaying duration form. + * + * @copyright 2011 Artem Andreev + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ class mod_attendance_duration_form extends moodleform { + /** + * Called to define this moodle form + * + * @return void + */ public function definition() { global $CFG; diff --git a/export_form.php b/export_form.php index 98db6a7..e43e1c6 100644 --- a/export_form.php +++ b/export_form.php @@ -24,11 +24,22 @@ require_once($CFG->libdir.'/formslib.php'); +/** + * class for displaying export form. + * + * @copyright 2011 Artem Andreev + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ class mod_attendance_export_form extends moodleform { + /** + * Called to define this moodle form + * + * @return void + */ public function definition() { - global $CFG, $USER; + global $USER; $mform =& $this->_form; $course = $this->_customdata['course']; @@ -77,7 +88,6 @@ class mod_attendance_export_form extends moodleform { $this->add_action_buttons(false, $submit_string); $mform->addElement('hidden', 'id', $cm->id); - } } diff --git a/lang/en/attendance.php b/lang/en/attendance.php index 86b6496..3fa70bd 100644 --- a/lang/en/attendance.php +++ b/lang/en/attendance.php @@ -14,6 +14,14 @@ // You should have received a copy of the GNU General Public License // along with Moodle. If not, see . +/** + * Strings for component 'attendance', language 'en' + * + * @package mod_attendance + * @copyright 2011 Artem Andreev + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ + $string['attendance:addinstance'] = 'Add a new attendance activity'; $string['Aacronym'] = 'A'; $string['Afull'] = 'Absent'; diff --git a/lib.php b/lib.php index d005d0e..32d65e5 100644 --- a/lib.php +++ b/lib.php @@ -76,7 +76,7 @@ function attendance_add_instance($attendance) { att_add_default_statuses($attendance->id); attendance_grade_item_update($attendance); - // attendance_update_grades($attendance); + return $attendance->id; } @@ -290,7 +290,6 @@ function attendance_grade_item_update($attendance, $grades=null) { if (! $course = $DB->get_record('course', array('id'=> $attendance->course))) { error("Course is misconfigured"); } - // $attendance->grade = get_maxgrade($course); if (!empty($attendance->cmidnumber)) { $params = array('itemname'=>$attendance->name, 'idnumber'=>$attendance->cmidnumber); diff --git a/locallib.php b/locallib.php index c8a7070..92191ed 100644 --- a/locallib.php +++ b/locallib.php @@ -841,7 +841,8 @@ class attendance { $sesslog[$sid]->studentid = $sid; // We check is_numeric on this above. $sesslog[$sid]->statusid = $value; // We check is_numeric on this above. $sesslog[$sid]->statusset = $statuses; - $sesslog[$sid]->remarks = array_key_exists('remarks'.$sid, $formdata) ? clean_param($formdata['remarks'.$sid], PARAM_TEXT) : ''; + $sesslog[$sid]->remarks = array_key_exists('remarks'.$sid, $formdata) ? + clean_param($formdata['remarks'.$sid], PARAM_TEXT) : ''; $sesslog[$sid]->sessionid = $this->pageparams->sessionid; $sesslog[$sid]->timetaken = $now; $sesslog[$sid]->takenby = $USER->id; diff --git a/mod_form.php b/mod_form.php index e631205..5704a35 100644 --- a/mod_form.php +++ b/mod_form.php @@ -28,11 +28,20 @@ if (!defined('MOODLE_INTERNAL')) { require_once($CFG->dirroot.'/course/moodleform_mod.php'); +/** + * class for displaying add/update form. + * + * @copyright 2011 Artem Andreev + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ class mod_attendance_mod_form extends moodleform_mod { + /** + * Called to define this moodle form + * + * @return void + */ public function definition() { - - global $CFG; $mform =& $this->_form; $mform->addElement('header', 'general', get_string('general', 'form')); @@ -46,8 +55,6 @@ class mod_attendance_mod_form extends moodleform_mod { $mform->setDefault('grade', 100); $this->standard_coursemodule_elements(true); - $this->add_action_buttons(); } - } diff --git a/renderables.php b/renderables.php index fb4a44b..4234bcd 100644 --- a/renderables.php +++ b/renderables.php @@ -32,6 +32,9 @@ require_once(dirname(__FILE__).'/locallib.php'); * * Proxy class for security reasons (renderers must not have access to all attendance methods) * + * @copyright 2011 Artem Andreev + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * */ class attendance_tabs implements renderable { const TAB_SESSIONS = 1; @@ -189,6 +192,8 @@ class attendance_filter_controls implements renderable { /** * Represents info about attendance sessions taking into account view parameters. * + * @copyright 2011 Artem Andreev + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class attendance_manage_data implements renderable { /** @var array of sessions*/ diff --git a/renderer.php b/renderer.php index da290ab..2b7dae2 100644 --- a/renderer.php +++ b/renderer.php @@ -31,6 +31,7 @@ require_once(dirname(__FILE__).'/renderhelpers.php'); /** * Attendance module renderer class * + * @copyright 2011 Artem Andreev * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class mod_attendance_renderer extends plugin_renderer_base { diff --git a/renderhelpers.php b/renderhelpers.php index 417bc30..e25bfb0 100644 --- a/renderhelpers.php +++ b/renderhelpers.php @@ -27,7 +27,10 @@ defined('MOODLE_INTERNAL') || die(); require_once(dirname(__FILE__).'/renderables.php'); /** - * Template method for generating user's session's cells + * class Template method for generating user's session's cells + * + * @copyright 2011 Artem Andreev + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class user_sessions_cells_generator { protected $cells = array(); @@ -103,6 +106,12 @@ class user_sessions_cells_generator { } } +/** + * class Template method for generating user's session's cells in html + * + * @copyright 2011 Artem Andreev + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ class user_sessions_cells_html_generator extends user_sessions_cells_generator { private $cell; @@ -154,6 +163,12 @@ class user_sessions_cells_html_generator extends user_sessions_cells_generator { } } +/** + * class Template method for generating user's session's cells in text + * + * @copyright 2011 Artem Andreev + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ class user_sessions_cells_text_generator extends user_sessions_cells_generator { private $enrolments_info_cell_text; diff --git a/sessions.php b/sessions.php index 109105d..cdef07a 100644 --- a/sessions.php +++ b/sessions.php @@ -129,7 +129,8 @@ switch ($att->pageparams->action) { } $sessionsids = implode('_', $sessid); - $params = array('action' => $att->pageparams->action, 'sessionsids' => $sessionsids, 'confirm' => 1, 'sesskey' => sesskey()); + $params = array('action' => $att->pageparams->action, 'sessionsids' => $sessionsids, + 'confirm' => 1, 'sesskey' => sesskey()); echo $OUTPUT->header(); echo $OUTPUT->heading(get_string('attendanceforthecourse', 'attendance').' :: ' .$course->fullname); diff --git a/update_form.php b/update_form.php index 83964c7..980c9ce 100644 --- a/update_form.php +++ b/update_form.php @@ -25,10 +25,22 @@ require_once($CFG->libdir.'/formslib.php'); +/** + * class for displaying update form. + * + * @copyright 2011 Artem Andreev + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ class mod_attendance_update_form extends moodleform { + + /** + * Called to define this moodle form + * + * @return void + */ public function definition() { - global $CFG, $DB; + global $DB; $mform =& $this->_form; $course = $this->_customdata['course'];