More coding guideline stuff - phpdocs.

add_form.php

@@ -24,8 +24,19 @@
 
 require_once($CFG->libdir.'/formslib.php');
 
+/**
+ * class for displaying add form.
+ *
+ * @copyright  2011 Artem Andreev <andreev.artem@gmail.com>
+ * @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);
 

backup/moodle2/backup_attforblock_activity_task.class.php → backup/moodle2/backup_attendance_activity_task.class.php

@@ -17,8 +17,7 @@
 /**
  * Class {@link backup_attendance_activity_task} definition
  *
- * @package    mod
+ * @package    mod_attendance
- * @subpackage attendance
  * @copyright  2011 Artem Andreev <andreev.artem@gmail.com>
  * @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 <andreev.artem@gmail.com>
+ * @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;

backup/moodle2/backup_attforblock_stepslib.php → 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
+ * @package    mod_attendance
- * @subpackage attendance
  * @copyright  2011 Artem Andreev <andreev.artem@gmail.com>
  * @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 <andreev.artem@gmail.com>
+ * @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?

backup/moodle2/backup_attforblock_settingslib.php

@@ -1,26 +0,0 @@
-<?php
-// This file is part of Moodle - http://moodle.org/
-//
-// Moodle is free software: you can redistribute it and/or modify
-// it under the terms of the GNU General Public License as published by
-// the Free Software Foundation, either version 3 of the License, or
-// (at your option) any later version.
-//
-// Moodle is distributed in the hope that it will be useful,
-// but WITHOUT ANY WARRANTY; without even the implied warranty of
-// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-// GNU General Public License for more details.
-//
-// You should have received a copy of the GNU General Public License
-// along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
-
-/**
- * @package    mod
- * @subpackage attendance
- * @copyright  2011 Artem Andreev <andreev.artem@gmail.com>
- * @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).

backup/moodle2/restore_attforblock_activity_task.class.php → backup/moodle2/restore_attendance_activity_task.class.php

@@ -15,8 +15,9 @@
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
 /**
- * @package    mod
+ * Define all the restore steps that will be used by the restore_attendance_activity_task
- * @subpackage attendance
+ *
+ * @package    mod_attendance
  * @copyright  2011 Artem Andreev <andreev.artem@gmail.com>
  * @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
+ * Attendance restore task that provides all the settings and steps to perform one complete restore of the activity
- * complete restore of the activity
+ *
+ * @copyright  2011 Artem Andreev <andreev.artem@gmail.com>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class restore_attendance_activity_task extends restore_activity_task {
 

backup/moodle2/restore_attforblock_stepslib.php → backup/moodle2/restore_attendance_stepslib.php

@@ -15,8 +15,9 @@
 // along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
 
 /**
- * @package    mod
+ * Structure step to restore one attendance activity
- * @subpackage attendance
+ *
+ * @package    mod_attendance
  * @copyright  2011 Artem Andreev <andreev.artem@gmail.com>
  * @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
- */
+ *
-
+ * @copyright  2011 Artem Andreev <andreev.artem@gmail.com>
-/**
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
- * Structure step to restore one attendance activity
  */
 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');
     }

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 <http://www.gnu.org/licenses/>.
 
-//
+/**
-// Capability definitions for the assignment module.
+ * Capability definitions for this module.
-//
+ *
-// The capabilities are loaded into the database table when the module is
+ * @package   mod_attendance
-// installed or updated. Whenever the capability definitions are updated,
+ * @copyright  2011 Artem Andreev <andreev.artem@gmail.com>
-// the module version number should be bumped up.
+ * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
-//
+ */
-// 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>:<capabilityname>
-//
-// component_name should be the same as the directory name of the mod or block.
-//
-// Core moodle capabilities are defined thus:
-//    moodle/<capabilityclass>:<capabilityname>
-//
-// Examples: mod/forum:viewpost
-//           block/recent_activity:view
-//           moodle/site:deleteuser
-//
-// The variable name for the capability definitions array follows the format
-//   $<componenttype>_<component_name>_capabilities
-//
-// For the core capabilities, the variable is $moodle_capabilities.
 
 
 $capabilities = array(

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 <http://www.gnu.org/licenses/>.
 
-
 /**
- * This file replaces the legacy STATEMENTS section in db/install.xml,
+ * post installation hook for adding data.
- * lib.php/modulename_install() post installation hook and partially defaults.php
  *
- * @package    mod
+ * @package    mod_attendance
- * @subpackage attendance
  * @copyright  2011 Artem Andreev <andreev.artem@gmail.com>
  * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */

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 <http://www.gnu.org/licenses/>.
 
-// This file keeps track of upgrades to
+/**
-// the attendance module.
+ * upgrade processes for this module.
+ *
+ * @package   mod_attendance
+ * @copyright 2011 Artem Andreev <andreev.artem@gmail.com>
+ * @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;
 }

duration_form.php

@@ -24,8 +24,19 @@
 
 require_once($CFG->libdir.'/formslib.php');
 
+/**
+ * class for displaying duration form.
+ *
+ * @copyright  2011 Artem Andreev <andreev.artem@gmail.com>
+ * @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;

export_form.php

@@ -24,11 +24,22 @@
 
 require_once($CFG->libdir.'/formslib.php');
 
+/**
+ * class for displaying export form.
+ *
+ * @copyright  2011 Artem Andreev <andreev.artem@gmail.com>
+ * @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);
-
     }
 }
 

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 <http://www.gnu.org/licenses/>.
 
+/**
+ * Strings for component 'attendance', language 'en'
+ *
+ * @package   mod_attendance
+ * @copyright  2011 Artem Andreev <andreev.artem@gmail.com>
+ * @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';

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);

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;

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 <andreev.artem@gmail.com>
+ * @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();
     }
-
 }

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 <andreev.artem@gmail.com>
+ * @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 <andreev.artem@gmail.com>
+ * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class attendance_manage_data implements renderable {
     /** @var array of sessions*/

renderer.php

@@ -31,6 +31,7 @@ require_once(dirname(__FILE__).'/renderhelpers.php');
 /**
  * Attendance module renderer class
  *
+ * @copyright  2011 Artem Andreev <andreev.artem@gmail.com>
  * @license   http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
  */
 class mod_attendance_renderer extends plugin_renderer_base {

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 <andreev.artem@gmail.com>
+ * @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 <andreev.artem@gmail.com>
+ * @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 <andreev.artem@gmail.com>
+ * @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;
 

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);

update_form.php

@@ -25,10 +25,22 @@
 
 require_once($CFG->libdir.'/formslib.php');
 
+/**
+ * class for displaying update form.
+ *
+ * @copyright  2011 Artem Andreev <andreev.artem@gmail.com>
+ * @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'];