diff --git a/lib/completion/completion_aggregation.php b/lib/completion/completion_aggregation.php index 5591261f297..e7a07863781 100644 --- a/lib/completion/completion_aggregation.php +++ b/lib/completion/completion_aggregation.php @@ -1,5 +1,4 @@ - * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @author Aaron Barnes + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ + +defined('MOODLE_INTERNAL') || die(); require_once($CFG->libdir.'/completion/data_object.php'); /** * Course completion critieria aggregation + * + * @package core_completion + * @category completion + * @copyright 2009 Catalyst IT Ltd + * @author Aaron Barnes + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class completion_aggregation extends data_object { - /** - * DB Table - * @var string $table - */ + /* @var string Database table name that stores completion aggregation information */ public $table = 'course_completion_aggr_methd'; /** * Array of required table fields, must start with 'id'. - * @var array $required_fields + * Defaults to id, course, criteriatype, method, value + * @var array */ public $required_fields = array('id', 'course', 'criteriatype', 'method', 'value'); - /** - * Course id - * @access public - * @var int - */ + /* @var int Course id */ public $course; - /** - * Criteria type this aggregation method applies to, or NULL for overall course aggregation - * @access public - * @var int - */ + /* @var int Criteria type this aggregation method applies to, or NULL for overall course aggregation */ public $criteriatype; - /** - * Aggregation method (COMPLETION_AGGREGATION_* constant) - * @access public - * @var int - */ + /* @var int Aggregation method (COMPLETION_AGGREGATION_* constant)*/ public $method; - /** - * Method value - * @access public - * @var mixed - */ + /* @var mixed Method value */ public $value; /** * Finds and returns a data_object instance based on params. - * @static abstract * * @param array $params associative arrays varname=>value - * @return object data_object instance or false if none found. + * @return data_object instance of data_object or false if none found. */ public static function fetch($params) { return self::fetch_helper('course_completion_aggr_methd', __CLASS__, $params); @@ -86,7 +75,6 @@ class completion_aggregation extends data_object { /** * Finds and returns all data_object instances based on params. - * @static abstract * * @param array $params associative arrays varname=>value * @return array array of data_object insatnces or false if none found. @@ -95,9 +83,8 @@ class completion_aggregation extends data_object { /** * Set the aggregation method - * @access public - * @param $method int - * @return void + * + * @param int $method One of COMPLETION_AGGREGATION_ALL or COMPLETION_AGGREGATION_ANY */ public function setMethod($method) { $methods = array( diff --git a/lib/completion/completion_completion.php b/lib/completion/completion_completion.php index 67377894116..2b5d8bf4bad 100644 --- a/lib/completion/completion_completion.php +++ b/lib/completion/completion_completion.php @@ -1,5 +1,4 @@ . +/** + * Course completion status for a particular user/course + * + * @package core_completion + * @category completion + * @copyright 2009 Catalyst IT Ltd + * @author Aaron Barnes + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ + +defined('MOODLE_INTERNAL') || die(); +require_once($CFG->libdir.'/completion/data_object.php'); /** * Course completion status for a particular user/course * - * @package moodlecore + * @package core_completion + * @category completion * @copyright 2009 Catalyst IT Ltd - * @author Aaron Barnes - * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later - */ -require_once($CFG->libdir.'/completion/data_object.php'); - - -/** - * Course completion status for a particular user/course + * @author Aaron Barnes + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class completion_completion extends data_object { - /** - * DB Table - * @var string $table - */ + /* @var string $table Database table name that stores completion information */ public $table = 'course_completions'; - /** - * Array of required table fields, must start with 'id'. - * @var array $required_fields - */ + /* @var array $required_fields Array of required table fields, must start with 'id'. */ public $required_fields = array('id', 'userid', 'course', 'deleted', 'timenotified', 'timeenrolled', 'timestarted', 'timecompleted', 'reaggregate'); - /** - * User ID - * @access public - * @var int - */ + /* @var int $userid User ID */ public $userid; - /** - * Course ID - * @access public - * @var int - */ + /* @var int $course Course ID */ public $course; - /** - * Set to 1 if this record has been deleted - * @access public - * @var int - */ + /* @var int $deleted set to 1 if this record has been deleted */ public $deleted; - /** - * Timestamp the interested parties were notified - * of this user's completion - * @access public - * @var int - */ + /* @var int Timestamp the interested parties were notified of this user's completion. */ public $timenotified; - /** - * Time of course enrolment - * @see completion_completion::mark_enrolled() - * @access public - * @var int - */ + /* @var int Time of course enrolment {@link completion_completion::mark_enrolled()} */ public $timeenrolled; /** - * Time the user started their course completion - * @see completion_completion::mark_inprogress() - * @access public - * @var int + * Time the user started their course completion {@link completion_completion::mark_inprogress()} + * @var int */ public $timestarted; - /** - * Timestamp of course completion - * @see completion_completion::mark_complete() - * @access public - * @var int - */ + /* @var int Timestamp of course completion {@link completion_completion::mark_complete()} */ public $timecompleted; - /** - * Flag to trigger cron aggregation (timestamp) - * @access public - * @var int - */ + /* @var int Flag to trigger cron aggregation (timestamp) */ public $reaggregate; /** * Finds and returns a data_object instance based on params. - * @static abstract * - * @param array $params associative arrays varname=>value - * @return object data_object instance or false if none found. + * @param array $params associative arrays varname = >value + * @return data_object instance of data_object or false if none found. */ public static function fetch($params) { $params['deleted'] = null; @@ -120,8 +86,8 @@ class completion_completion extends data_object { /** * Return status of this completion - * @access public - * @return boolean + * + * @return bool */ public function is_complete() { return (bool) $this->timecompleted; @@ -132,9 +98,7 @@ class completion_completion extends data_object { * * If the user is already marked as started, no change will occur * - * @access public - * @param integer $timeenrolled Time enrolled (optional) - * @return void + * @param integer $timeenrolled Time enrolled (optional) */ public function mark_enrolled($timeenrolled = null) { @@ -153,12 +117,9 @@ class completion_completion extends data_object { /** * Mark this user as inprogress in this course * - * If the user is already marked as inprogress, - * the time will not be changed + * If the user is already marked as inprogress, the time will not be changed * - * @access public - * @param integer $timestarted Time started (optional) - * @return void + * @param integer $timestarted Time started (optional) */ public function mark_inprogress($timestarted = null) { @@ -185,9 +146,8 @@ class completion_completion extends data_object { * This generally happens when the required completion criteria * in the course are complete. * - * @access public - * @param integer $timecomplete Time completed (optional) - * @return void + * @param integer $timecomplete Time completed (optional) + * @return void */ public function mark_complete($timecomplete = null) { @@ -212,11 +172,8 @@ class completion_completion extends data_object { * Save course completion status * * This method creates a course_completions record if none exists - * @access public - * @return void */ private function _save() { - global $DB; if ($this->timeenrolled === null) { @@ -232,10 +189,10 @@ class completion_completion extends data_object { $this->reaggregate = 0; } - // Make sure timestarted is not null - if (!$this->timestarted) { - $this->timestarted = 0; - } + // Make sure timestarted is not null + if (!$this->timestarted) { + $this->timestarted = 0; + } $this->insert(); } diff --git a/lib/completion/completion_criteria.php b/lib/completion/completion_criteria.php index 293d318dd55..d93e9a043a2 100644 --- a/lib/completion/completion_criteria.php +++ b/lib/completion/completion_criteria.php @@ -1,6 +1,4 @@ . - /** * Course completion criteria * - * @package moodlecore + * @package core_completion + * @category completion * @copyright 2009 Catalyst IT Ltd - * @author Aaron Barnes - * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @author Aaron Barnes + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ + +defined('MOODLE_INTERNAL') || die(); require_once($CFG->libdir.'/completion/data_object.php'); require_once($CFG->libdir.'/completion/completion_criteria_completion.php'); - /** - * Criteria type constants - * Primarily for storing criteria type in the database + * Self completion criteria type + * Criteria type constant, primarily for storing criteria type in the database. */ define('COMPLETION_CRITERIA_TYPE_SELF', 1); + +/** + * Date completion criteria type + * Criteria type constant, primarily for storing criteria type in the database. + */ define('COMPLETION_CRITERIA_TYPE_DATE', 2); + +/** + * Unenrol completion criteria type + * Criteria type constant, primarily for storing criteria type in the database. + */ define('COMPLETION_CRITERIA_TYPE_UNENROL', 3); + +/** + * Activity completion criteria type + * Criteria type constant, primarily for storing criteria type in the database. + */ define('COMPLETION_CRITERIA_TYPE_ACTIVITY', 4); + +/** + * Duration completion criteria type + * Criteria type constant, primarily for storing criteria type in the database. + */ define('COMPLETION_CRITERIA_TYPE_DURATION', 5); + +/** + * Grade completion criteria type + * Criteria type constant, primarily for storing criteria type in the database. + */ define('COMPLETION_CRITERIA_TYPE_GRADE', 6); + +/** + * Role completion criteria type + * Criteria type constant, primarily for storing criteria type in the database. + */ define('COMPLETION_CRITERIA_TYPE_ROLE', 7); + +/** + * Course completion criteria type + * Criteria type constant, primarily for storing criteria type in the database. + */ define('COMPLETION_CRITERIA_TYPE_COURSE', 8); /** @@ -60,72 +94,64 @@ $COMPLETION_CRITERIA_TYPES = array( /** * Completion criteria abstract definition + * + * @package core_completion + * @category completion + * @copyright 2009 Catalyst IT Ltd + * @author Aaron Barnes + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ abstract class completion_criteria extends data_object { - /** - * DB Table - * @var string $table - */ + + /* @var string Database table name that stores completion criteria information */ public $table = 'course_completion_criteria'; /** * Array of required table fields, must start with 'id'. - * @var array $required_fields + * Defaults to id, course, criteriatype, module, moduleinstane, courseinstance, + * enrolperiod, timeend, gradepass, role + * @var array */ public $required_fields = array('id', 'course', 'criteriatype', 'module', 'moduleinstance', 'courseinstance', 'enrolperiod', 'timeend', 'gradepass', 'role'); - /** - * Course id - * @var int - */ + /* @var int Course id */ public $course; /** * Criteria type * One of the COMPLETION_CRITERIA_TYPE_* constants - * @var int + * @var int */ public $criteriatype; - /** - * Module type this criteria relates to (for activity criteria) - * @var string - */ + /* @var string Module type this criteria relates to (for activity criteria) */ public $module; - /** - * Course module instance id this criteria relates to (for activity criteria) - * @var int - */ + /* @var int Course module instance id this criteria relates to (for activity criteria) */ public $moduleinstance; /** * Period after enrolment completion will be triggered (for period criteria) - * @var int (days) + * The value here is the number of days as an int. + * @var int */ public $enrolperiod; /** * Date of course completion (for date criteria) - * @var int (timestamp) + * This is a timestamp value + * @var int */ public $date; - /** - * Passing grade required to complete course (for grade completion) - * @var float - */ + /* @var float Passing grade required to complete course (for grade completion) */ public $gradepass; - /** - * Role ID that has the ability to mark a user as complete (for role completion) - * @var int - */ + /* @var int Role ID that has the ability to mark a user as complete (for role completion) */ public $role; /** * Finds and returns all data_object instances based on params. - * @static abstract * * @param array $params associative arrays varname=>value * @return array array of data_object insatnces or false if none found. @@ -134,9 +160,9 @@ abstract class completion_criteria extends data_object { /** * Factory method for creating correct class object - * @static - * @param array - * @return object + * + * @param array $params associative arrays varname=>value + * @return completion_criteria */ public static function factory($params) { global $CFG, $COMPLETION_CRITERIA_TYPES; @@ -153,64 +179,64 @@ abstract class completion_criteria extends data_object { /** * Add appropriate form elements to the critieria form - * @access public - * @param object $mform Moodle forms object - * @param mixed $data optional - * @return void + * + * @param moodleform $mform Moodle forms object + * @param mixed $data optional Any additional data that can be used to set default values in the form + * @return void */ abstract public function config_form_display(&$mform, $data = null); /** * Update the criteria information stored in the database - * @access public - * @param array $data Form data - * @return void + * + * @param array $data Form data + * @return void */ abstract public function update_config(&$data); /** * Review this criteria and decide if the user has completed - * @access public - * @param object $completion The user's completion record - * @param boolean $mark Optionally set false to not save changes to database - * @return boolean + * + * @param object $completion The user's completion record + * @param boolean $mark Optionally set false to not save changes to database + * @return boolean */ abstract public function review($completion, $mark = true); /** * Return criteria title for display in reports - * @access public - * @return string + * + * @return string */ abstract public function get_title(); /** * Return a more detailed criteria title for display in reports - * @access public - * @return string + * + * @return string */ abstract public function get_title_detailed(); /** * Return criteria type title for display in reports - * @access public - * @return string + * + * @return string */ abstract public function get_type_title(); /** * Return criteria progress details for display in reports - * @access public - * @param object $completion The user's completion record - * @return array + * + * @param completion_completion $completion The user's completion record + * @return array */ abstract public function get_details($completion); /** * Return criteria status text for display in reports - * @access public - * @param object $completion The user's completion record - * @return string + * + * @param completion_completion $completion The user's completion record + * @return string */ public function get_status($completion) { return $completion->is_complete() ? get_string('yes') : get_string('no'); @@ -220,7 +246,7 @@ abstract class completion_criteria extends data_object { * Return true if the criteria's current status is different to what is sorted * in the database, e.g. pending an update * - * @param object $completion The user's criteria completion record + * @param completion_completion $completion The user's criteria completion record * @return bool */ public function is_pending($completion) { diff --git a/lib/completion/completion_criteria_activity.php b/lib/completion/completion_criteria_activity.php index 096d1572256..409bf42c08f 100644 --- a/lib/completion/completion_criteria_activity.php +++ b/lib/completion/completion_criteria_activity.php @@ -15,28 +15,38 @@ // You should have received a copy of the GNU General Public License // along with Moodle. If not, see . +/** + * This file contains the activity completion criteria type class and any + * supporting functions it may require. + * + * @package core_completion + * @category completion + * @copyright 2009 Catalyst IT Ltd + * @author Aaron Barnes + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ + +defined('MOODLE_INTERNAL') || die(); + /** * Course completion critieria - completion on activity completion * - * @package moodlecore + * @package core_completion + * @category completion * @copyright 2009 Catalyst IT Ltd - * @author Aaron Barnes - * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @author Aaron Barnes + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class completion_criteria_activity extends completion_criteria { - /** - * Criteria type constant - * @var int - */ + /* @var int Criteria [COMPLETION_CRITERIA_TYPE_ACTIVITY] */ public $criteriatype = COMPLETION_CRITERIA_TYPE_ACTIVITY; /** * Finds and returns a data_object instance based on params. - * @static abstract * * @param array $params associative arrays varname=>value - * @return object data_object instance or false if none found. + * @return completion_criteria_activity data_object instance or false if none found. */ public static function fetch($params) { $params['criteriatype'] = COMPLETION_CRITERIA_TYPE_ACTIVITY; @@ -45,10 +55,9 @@ class completion_criteria_activity extends completion_criteria { /** * Add appropriate form elements to the critieria form - * @access public - * @param object $mform Moodle forms object - * @param mixed $data optional - * @return void + * + * @param moodleform $mform Moodle forms object + * @param stdClass $data details of various modules */ public function config_form_display(&$mform, $data = null) { $mform->addElement('checkbox', 'criteria_activity['.$data->id.']', ucfirst(self::get_mod_name($data->module)).' - '.$data->name); @@ -60,9 +69,8 @@ class completion_criteria_activity extends completion_criteria { /** * Update the criteria information stored in the database - * @access public - * @param array $data Form data - * @return void + * + * @param stdClass $data Form data */ public function update_config(&$data) { global $DB; @@ -84,10 +92,9 @@ class completion_criteria_activity extends completion_criteria { /** * Get module instance module type - * @static - * @access public - * @param int $type Module type id - * @return string + * + * @param int $type Module type id + * @return string */ public static function get_mod_name($type) { static $types; @@ -101,9 +108,10 @@ class completion_criteria_activity extends completion_criteria { } /** - * Get module instance - * @access public - * @return object|false + * Gets the module instance from the database and returns it. + * If no module instance exists this function returns false. + * + * @return stdClass|bool */ public function get_mod_instance() { global $DB; @@ -124,10 +132,10 @@ class completion_criteria_activity extends completion_criteria { /** * Review this criteria and decide if the user has completed - * @access public - * @param object $completion The user's completion record - * @param boolean $mark Optionally set false to not save changes to database - * @return boolean + * + * @param completion_completion $completion The user's completion record + * @param bool $mark Optionally set false to not save changes to database + * @return bool */ public function review($completion, $mark = true) { global $DB; @@ -152,8 +160,8 @@ class completion_criteria_activity extends completion_criteria { /** * Return criteria title for display in reports - * @access public - * @return string + * + * @return string */ public function get_title() { return get_string('activitiescompleted', 'completion'); @@ -161,7 +169,7 @@ class completion_criteria_activity extends completion_criteria { /** * Return a more detailed criteria title for display in reports - * @access public + * * @return string */ public function get_title_detailed() { @@ -174,7 +182,7 @@ class completion_criteria_activity extends completion_criteria { /** * Return criteria type title for display in reports - * @access public + * * @return string */ public function get_type_title() { @@ -182,9 +190,7 @@ class completion_criteria_activity extends completion_criteria { } /** - * Find user's who have completed this criteria - * @access public - * @return void + * Find users who have completed this criteria and mark them accordingly */ public function cron() { global $DB; @@ -238,9 +244,10 @@ class completion_criteria_activity extends completion_criteria { /** * Return criteria progress details for display in reports - * @access public - * @param object $completion The user's completion record - * @return array + * + * @param completion_completion $completion The user's completion record + * @return array An array with the following keys: + * type, criteria, requirement, status */ public function get_details($completion) { global $DB, $CFG; diff --git a/lib/completion/completion_criteria_completion.php b/lib/completion/completion_criteria_completion.php index 26127f8b128..f4d700d0772 100644 --- a/lib/completion/completion_criteria_completion.php +++ b/lib/completion/completion_criteria_completion.php @@ -1,5 +1,4 @@ - * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @author Aaron Barnes + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ -require_once($CFG->libdir.'/completion/data_object.php'); +defined('MOODLE_INTERNAL') || die(); +require_once($CFG->libdir.'/completion/data_object.php'); /** * Completion data for a specific user, course and critieria + * + * @package core_completion + * @category completion + * @copyright 2009 Catalyst IT Ltd + * @author Aaron Barnes + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class completion_criteria_completion extends data_object { - /** - * DB Table - * @var string $table - */ + /* @var string Database table that stores completion type criteria */ public $table = 'course_completion_crit_compl'; - /** - * Array of required table fields, must start with 'id'. - * @var array $required_fields - */ + /* @var array Array of required table fields, must start with 'id'. */ public $required_fields = array('id', 'userid', 'course', 'criteriaid', 'gradefinal', 'rpl', 'deleted', 'unenroled', 'timecompleted'); - /** - * User ID - * @access public - * @var int - */ + /* @var int User ID */ public $userid; - /** - * Course ID - * @access public - * @var int - */ + /* @var int course ID */ public $course; - /** - * The id of the course completion criteria this completion references - * @access public - * @var int - */ + /* @var int The id of the course completion criteria this completion references */ public $criteriaid; - /** - * The final grade for the user in the course (if completing a grade criteria) - * @access public - * @var float - */ + /* @var float The final grade for the user in the course (if completing a grade criteria) */ public $gradefinal; - /** - * Record of prior learning, leave blank if none - * @access public - * @var string - */ + /* @var string Record of prior learning, leave blank if none */ public $rpl; - /** - * Course deleted flag - * @access public - * @var boolean - */ + /* @var bool Course deleted flag */ public $deleted; - /** - * Timestamp of user unenrolment (if completing a unenrol criteria) - * @access public - * @var int (timestamp) - */ + /* @var int Timestamp of user unenrolment (if completing a unenrol criteria) */ public $unenroled; - /** - * Timestamp of course criteria completion - * @see completion_criteria_completion::mark_complete() - * @access public - * @var int (timestamp) - */ + /* @var int Timestamp of course criteria completion {@link completion_criteria_completion::mark_complete()} */ public $timecompleted; - /** - * Associated criteria object - * @access private - * @var object completion_criteria - */ + /* @var completion_criterria Associated criteria object */ private $_criteria; /** * Finds and returns a data_object instance based on params. - * @static abstract * * @param array $params associative arrays varname=>value - * @return object data_object instance or false if none found. + * @return data_object instance of data_object or false if none found. */ public static function fetch($params) { $params['deleted'] = null; @@ -121,7 +84,6 @@ class completion_criteria_completion extends data_object { /** * Finds and returns all data_object instances based on params. - * @static abstract * * @param array $params associative arrays varname=>value * @return array array of data_object insatnces or false if none found. @@ -130,8 +92,8 @@ class completion_criteria_completion extends data_object { /** * Return status of this criteria completion - * @access public - * @return boolean + * + * @return bool */ public function is_complete() { return (bool) $this->timecompleted; @@ -141,8 +103,6 @@ class completion_criteria_completion extends data_object { * Mark this criteria complete for the associated user * * This method creates a course_completion_crit_compl record - * @access public - * @return void */ public function mark_complete() { // Create record @@ -166,9 +126,8 @@ class completion_criteria_completion extends data_object { /** * Attach a preloaded criteria object to this object - * @access public + * * @param $criteria object completion_criteria - * @return void */ public function attach_criteria(completion_criteria $criteria) { $this->_criteria = $criteria; @@ -177,13 +136,12 @@ class completion_criteria_completion extends data_object { /** * Return the associated criteria with this completion * If nothing attached, load from the db - * @access public - * @return object completion_criteria + * + * @return completion_criteria */ public function get_criteria() { - if (!$this->_criteria) - { + if (!$this->_criteria) { global $DB; $params = array( @@ -199,10 +157,9 @@ class completion_criteria_completion extends data_object { } /** - * Return criteria status text for display in reports - * @see completion_criteria::get_status() - * @access public - * @return string + * Return criteria status text for display in reports {@link completion_criteria::get_status()} + * + * @return string */ public function get_status() { return $this->_criteria->get_status($this); diff --git a/lib/completion/completion_criteria_course.php b/lib/completion/completion_criteria_course.php index 5f7acf209e9..882ee6365c2 100644 --- a/lib/completion/completion_criteria_course.php +++ b/lib/completion/completion_criteria_course.php @@ -1,5 +1,4 @@ . +/** + * This file contains the course criteria type. + * + * @package core_completion + * @category completion + * @copyright 2009 Catalyst IT Ltd + * @author Aaron Barnes + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ + +defined('MOODLE_INTERNAL') || die(); + /** * Course completion critieria - completion on course completion * * This course completion criteria depends on another course with * completion enabled to be marked as complete for this user * - * @package moodlecore + * @package core_completion + * @category completion * @copyright 2009 Catalyst IT Ltd - * @author Aaron Barnes - * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @author Aaron Barnes + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class completion_criteria_course extends completion_criteria { - /** - * Criteria type constant - * @var int - */ + /* @var int Criteria type constant */ public $criteriatype = COMPLETION_CRITERIA_TYPE_COURSE; /** * Finds and returns a data_object instance based on params. - * @static abstract * * @param array $params associative arrays varname=>value - * @return object data_object instance or false if none found. + * @return data_object instance of data_object or false if none found. */ public static function fetch($params) { $params['criteriatype'] = COMPLETION_CRITERIA_TYPE_COURSE; @@ -48,10 +56,9 @@ class completion_criteria_course extends completion_criteria { /** * Add appropriate form elements to the critieria form - * @access public - * @param object $mform Moodle forms object - * @param mixed $data optional - * @return void + * + * @param moodle_form $mform Moodle forms object + * @param stdClass $data data used to define default value of the form */ public function config_form_display(&$mform, $data = null) { global $CFG; @@ -66,9 +73,8 @@ class completion_criteria_course extends completion_criteria { /** * Update the criteria information stored in the database - * @access public - * @param array $data Form data - * @return void + * + * @param array $data Form data */ public function update_config(&$data) { @@ -87,10 +93,10 @@ class completion_criteria_course extends completion_criteria { /** * Review this criteria and decide if the user has completed - * @access public - * @param object $completion The user's completion record - * @param boolean $mark Optionally set false to not save changes to database - * @return boolean + * + * @param completion_completion $completion The user's completion record + * @param bool $mark Optionally set false to not save changes to database + * @return bool */ public function review($completion, $mark = true) { global $DB; @@ -113,8 +119,8 @@ class completion_criteria_course extends completion_criteria { /** * Return criteria title for display in reports - * @access public - * @return string + * + * @return string */ public function get_title() { return get_string('prerequisitescompleted', 'completion'); @@ -122,8 +128,8 @@ class completion_criteria_course extends completion_criteria { /** * Return a more detailed criteria title for display in reports - * @access public - * @return string + * + * @return string */ public function get_title_detailed() { global $DB; @@ -136,8 +142,8 @@ class completion_criteria_course extends completion_criteria { /** * Return criteria type title for display in reports - * @access public - * @return string + * + * @return string */ public function get_type_title() { return get_string('prerequisites', 'completion'); @@ -145,8 +151,6 @@ class completion_criteria_course extends completion_criteria { /** * Find user's who have completed this criteria - * @access public - * @return void */ public function cron() { @@ -197,9 +201,10 @@ class completion_criteria_course extends completion_criteria { /** * Return criteria progress details for display in reports - * @access public - * @param object $completion The user's completion record - * @return array + * + * @param completion_completion $completion The user's completion record + * @return array An array with the following keys: + * type, criteria, requirement, status */ public function get_details($completion) { global $CFG, $DB; diff --git a/lib/completion/completion_criteria_date.php b/lib/completion/completion_criteria_date.php index dfe1717ed33..e6e81c09148 100644 --- a/lib/completion/completion_criteria_date.php +++ b/lib/completion/completion_criteria_date.php @@ -1,5 +1,4 @@ . +/** + * This file contains the date criteria type + * + * @package core_completion + * @category completion + * @copyright 2009 Catalyst IT Ltd + * @author Aaron Barnes + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ + +defined('MOODLE_INTERNAL') || die(); + /** * Course completion critieria - completion on specified date * - * @package moodlecore + * @package core_completion + * @category completion * @copyright 2009 Catalyst IT Ltd - * @author Aaron Barnes - * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @author Aaron Barnes + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class completion_criteria_date extends completion_criteria { - /** - * Criteria type constant - * @var int - */ + /* @var int Criteria type constant [COMPLETION_CRITERIA_TYPE_DATE] */ public $criteriatype = COMPLETION_CRITERIA_TYPE_DATE; /** * Finds and returns a data_object instance based on params. - * @static abstract * * @param array $params associative arrays varname=>value - * @return object data_object instance or false if none found. + * @return data_object data_object instance or false if none found. */ public static function fetch($params) { $params['criteriatype'] = COMPLETION_CRITERIA_TYPE_DATE; @@ -45,13 +53,11 @@ class completion_criteria_date extends completion_criteria { /** * Add appropriate form elements to the critieria form - * @access public - * @param object $mform Moodle forms object - * @param mixed $data optional - * @return void + * + * @param moodleform $mform Moodle forms object + * @param stdClass $data not used */ - public function config_form_display(&$mform, $data = null) - { + public function config_form_display(&$mform, $data = null) { $mform->addElement('checkbox', 'criteria_date', get_string('enable')); $mform->addElement('date_selector', 'criteria_date_value', get_string('afterspecifieddate', 'completion')); @@ -66,12 +72,10 @@ class completion_criteria_date extends completion_criteria { /** * Update the criteria information stored in the database - * @access public - * @param array $data Form data - * @return void + * + * @param stdClass $data Form data */ public function update_config(&$data) { - if (!empty($data->criteria_date)) { $this->course = $data->id; $this->timeend = $data->criteria_date_value; @@ -81,13 +85,12 @@ class completion_criteria_date extends completion_criteria { /** * Review this criteria and decide if the user has completed - * @access public - * @param object $completion The user's completion record - * @param boolean $mark Optionally set false to not save changes to database - * @return boolean + * + * @param completion_completion $completion The user's completion record + * @param bool $mark Optionally set false to not save changes to database + * @return bool */ - public function review($completion, $mark = true) - { + public function review($completion, $mark = true) { // If current time is past timeend if ($this->timeend && $this->timeend < time()) { if ($mark) { @@ -96,14 +99,13 @@ class completion_criteria_date extends completion_criteria { return true; } - return false; } /** * Return criteria title for display in reports - * @access public - * @return string + * + * @return string */ public function get_title() { return get_string('date'); @@ -111,8 +113,8 @@ class completion_criteria_date extends completion_criteria { /** * Return a more detailed criteria title for display in reports - * @access public - * @return string + * + * @return string */ public function get_title_detailed() { return userdate($this->timeend, '%d-%h-%y'); @@ -120,8 +122,8 @@ class completion_criteria_date extends completion_criteria { /** * Return criteria type title for display in reports - * @access public - * @return string + * + * @return string */ public function get_type_title() { return get_string('date'); @@ -130,9 +132,9 @@ class completion_criteria_date extends completion_criteria { /** * Return criteria status text for display in reports - * @access public - * @param object $completion The user's completion record - * @return string + * + * @param completion_completion $completion The user's completion record + * @return string */ public function get_status($completion) { return $completion->is_complete() ? get_string('yes') : userdate($this->timeend, '%d-%h-%y'); @@ -140,8 +142,6 @@ class completion_criteria_date extends completion_criteria { /** * Find user's who have completed this criteria - * @access public - * @return void */ public function cron() { global $DB; @@ -187,9 +187,10 @@ class completion_criteria_date extends completion_criteria { /** * Return criteria progress details for display in reports - * @access public - * @param object $completion The user's completion record - * @return array + * + * @param completion_completion $completion The user's completion record + * @return array An array with the following keys: + * type, criteria, requirement, status */ public function get_details($completion) { $details = array(); diff --git a/lib/completion/completion_criteria_duration.php b/lib/completion/completion_criteria_duration.php index bc2c8a07883..97bcb923b00 100644 --- a/lib/completion/completion_criteria_duration.php +++ b/lib/completion/completion_criteria_duration.php @@ -1,5 +1,4 @@ - * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @author Aaron Barnes + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ + +defined('MOODLE_INTERNAL') || die(); + +/** + * Course completion critieria - completion after specific duration from course enrolment + * + * @package core_completion + * @category completion + * @copyright 2009 Catalyst IT Ltd + * @author Aaron Barnes + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class completion_criteria_duration extends completion_criteria { - /** - * Criteria type constant - * @var int - */ + /* @var int Criteria type constant [COMPLETION_CRITERIA_TYPE_DURATION] */ public $criteriatype = COMPLETION_CRITERIA_TYPE_DURATION; /** * Finds and returns a data_object instance based on params. - * @static abstract * * @param array $params associative arrays varname=>value - * @return object data_object instance or false if none found. + * @return data_object data_object instance or false if none found. */ public static function fetch($params) { $params['criteriatype'] = COMPLETION_CRITERIA_TYPE_DURATION; @@ -45,10 +53,9 @@ class completion_criteria_duration extends completion_criteria { /** * Add appropriate form elements to the critieria form - * @access public - * @param object $mform Moodle forms object - * @param mixed $data optional - * @return void + * + * @param moodleform $mform Moodle forms object + * @param stdClass $data not used */ public function config_form_display(&$mform, $data = null) { @@ -69,12 +76,10 @@ class completion_criteria_duration extends completion_criteria { /** * Update the criteria information stored in the database - * @access public - * @param array $data Form data - * @return void + * + * @param stdClass $data Form data */ public function update_config(&$data) { - if (!empty($data->criteria_duration)) { $this->course = $data->id; $this->enrolperiod = $data->criteria_duration_days; @@ -84,8 +89,9 @@ class completion_criteria_duration extends completion_criteria { /** * Get the time this user was enroled - * @param object $completion - * @return int + * + * @param completion_completion $completion + * @return int */ private function get_timeenrolled($completion) { global $DB; @@ -100,10 +106,10 @@ class completion_criteria_duration extends completion_criteria { /** * Review this criteria and decide if the user has completed - * @access public - * @param object $completion The user's completion record - * @param boolean $mark Optionally set false to not save changes to database - * @return boolean + * + * @param completion_completion $completion The user's completion record + * @param bool $mark Optionally set false to not save changes to database + * @return bool */ public function review($completion, $mark = true) { $timeenrolled = $this->get_timeenrolled($completion); @@ -126,8 +132,8 @@ class completion_criteria_duration extends completion_criteria { /** * Return criteria title for display in reports - * @access public - * @return string + * + * @return string */ public function get_title() { return get_string('enrolmentduration', 'completion'); @@ -135,8 +141,8 @@ class completion_criteria_duration extends completion_criteria { /** * Return a more detailed criteria title for display in reports - * @access public - * @return string + * + * @return string */ public function get_title_detailed() { return ceil($this->enrolperiod / (60 * 60 * 24)) . ' days'; @@ -144,8 +150,8 @@ class completion_criteria_duration extends completion_criteria { /** * Return criteria type title for display in reports - * @access public - * @return string + * + * @return string */ public function get_type_title() { return get_string('days', 'completion'); @@ -153,9 +159,9 @@ class completion_criteria_duration extends completion_criteria { /** * Return criteria status text for display in reports - * @access public - * @param object $completion The user's completion record - * @return string + * + * @param completion_completion $completion The user's completion record + * @return string */ public function get_status($completion) { $timeenrolled = $this->get_timeenrolled($completion); @@ -169,8 +175,6 @@ class completion_criteria_duration extends completion_criteria { /** * Find user's who have completed this criteria - * @access public - * @return void */ public function cron() { global $DB; @@ -240,9 +244,10 @@ class completion_criteria_duration extends completion_criteria { /** * Return criteria progress details for display in reports - * @access public - * @param object $completion The user's completion record - * @return array + * + * @param completion_completion $completion The user's completion record + * @return array An array with the following keys: + * type, criteria, requirement, status */ public function get_details($completion) { $details = array(); diff --git a/lib/completion/completion_criteria_grade.php b/lib/completion/completion_criteria_grade.php index c1ff8a07122..e452454d080 100644 --- a/lib/completion/completion_criteria_grade.php +++ b/lib/completion/completion_criteria_grade.php @@ -1,5 +1,4 @@ - * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @author Aaron Barnes + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ + +defined('MOODLE_INTERNAL') || die(); require_once $CFG->dirroot.'/grade/lib.php'; require_once $CFG->dirroot.'/grade/querylib.php'; /** * Course completion critieria - completion on achieving course grade + * + * @package core_completion + * @category completion + * @copyright 2009 Catalyst IT Ltd + * @author Aaron Barnes + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class completion_criteria_grade extends completion_criteria { - /** - * Criteria type constant - * @var int - */ + /* @var int Criteria type constant [COMPLETION_CRITERIA_TYPE_GRADE] */ public $criteriatype = COMPLETION_CRITERIA_TYPE_GRADE; /** * Finds and returns a data_object instance based on params. - * @static abstract * - * @param array $params associative arrays varname=>value - * @return object data_object instance or false if none found. + * @param array $params associative array varname => value of various + * parameters used to fetch data_object + * @return data_object data_object instance or false if none found. */ public static function fetch($params) { $params['criteriatype'] = COMPLETION_CRITERIA_TYPE_GRADE; @@ -51,10 +56,9 @@ class completion_criteria_grade extends completion_criteria { /** * Add appropriate form elements to the critieria form - * @access public - * @param object $mform Moodle forms object - * @param mixed $data optional - * @return void + * + * @param moodle_form $mform Moodle forms object + * @param stdClass $data containing default values to be set in the form */ public function config_form_display(&$mform, $data = null) { $mform->addElement('checkbox', 'criteria_grade', get_string('enable')); @@ -69,9 +73,8 @@ class completion_criteria_grade extends completion_criteria { /** * Update the criteria information stored in the database - * @access public - * @param array $data Form data - * @return void + * + * @param stdClass $data Form data */ public function update_config(&$data) { @@ -86,10 +89,9 @@ class completion_criteria_grade extends completion_criteria { /** * Get user's course grade in this course - * @static - * @access private - * @param object $completion - * @return float + * + * @param completion_completion $completion an instance of completion_completion class + * @return float */ private function get_grade($completion) { $grade = grade_get_course_grade($completion->userid, $this->course); @@ -98,10 +100,10 @@ class completion_criteria_grade extends completion_criteria { /** * Review this criteria and decide if the user has completed - * @access public - * @param object $completion The user's completion record - * @param boolean $mark Optionally set false to not save changes to database - * @return boolean + * + * @param completion_completion $completion The user's completion record + * @param bool $mark Optionally set false to not save changes to database + * @return bool */ public function review($completion, $mark = true) { // Get user's course grade @@ -122,7 +124,7 @@ class completion_criteria_grade extends completion_criteria { /** * Return criteria title for display in reports - * @access public + * * @return string */ public function get_title() { @@ -131,8 +133,8 @@ class completion_criteria_grade extends completion_criteria { /** * Return a more detailed criteria title for display in reports - * @access public - * @return string + * + * @return string */ public function get_title_detailed() { return (float) $this->gradepass . '% required'; @@ -140,8 +142,8 @@ class completion_criteria_grade extends completion_criteria { /** * Return criteria type title for display in reports - * @access public - * @return string + * + * @return string */ public function get_type_title() { return get_string('grade'); @@ -149,9 +151,9 @@ class completion_criteria_grade extends completion_criteria { /** * Return criteria status text for display in reports - * @access public - * @param object $completion The user's completion record - * @return string + * + * @param completion_completion $completion The user's completion record + * @return string */ public function get_status($completion) { // Cast as floats to get rid of excess decimal places @@ -167,8 +169,6 @@ class completion_criteria_grade extends completion_criteria { /** * Find user's who have completed this criteria - * @access public - * @return void */ public function cron() { global $DB; @@ -223,9 +223,10 @@ class completion_criteria_grade extends completion_criteria { /** * Return criteria progress details for display in reports - * @access public - * @param object $completion The user's completion record - * @return array + * + * @param completion_completion $completion The user's completion record + * @return array An array with the following keys: + * type, criteria, requirement, status */ public function get_details($completion) { $details = array(); diff --git a/lib/completion/completion_criteria_role.php b/lib/completion/completion_criteria_role.php index 08927bccfaf..5b2d051cd00 100644 --- a/lib/completion/completion_criteria_role.php +++ b/lib/completion/completion_criteria_role.php @@ -1,5 +1,4 @@ - * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @author Aaron Barnes + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ + +defined('MOODLE_INTERNAL') || die(); + +/** + * Course completion critieria - marked by role + * + * @package core_completion + * @category completion + * @copyright 2009 Catalyst IT Ltd + * @author Aaron Barnes + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class completion_criteria_role extends completion_criteria { - /** - * Criteria type constant - * @var int - */ + /* @var int Criteria type constant [COMPLETION_CRITERIA_TYPE_ROLE] */ public $criteriatype = COMPLETION_CRITERIA_TYPE_ROLE; /** * Finds and returns a data_object instance based on params. - * @static abstract * * @param array $params associative arrays varname=>value - * @return object data_object instance or false if none found. + * @return data_object data_object instance or false if none found. */ public static function fetch($params) { $params['criteriatype'] = COMPLETION_CRITERIA_TYPE_ROLE; @@ -44,12 +52,11 @@ class completion_criteria_role extends completion_criteria { } /** - * Add appropriate form elements to the critieria form - * @access public - * @param object $mform Moodle forms object - * @param mixed $data optional - * @return void - */ + * Add appropriate form elements to the critieria form + * + * @param moodleform $mform Moodle forms object + * @param stdClass $data used to set default values of the form + */ public function config_form_display(&$mform, $data = null) { $mform->addElement('checkbox', 'criteria_role['.$data->id.']', $data->name); @@ -59,11 +66,10 @@ class completion_criteria_role extends completion_criteria { } } - /** + /** * Update the criteria information stored in the database - * @access public - * @param array $data Form data - * @return void + * + * @param stdClass $data Form data */ public function update_config(&$data) { @@ -82,9 +88,8 @@ class completion_criteria_role extends completion_criteria { /** * Mark this criteria as complete - * @access public - * @param object $completion The user's completion record - * @return void + * + * @param completion_completion $completion The user's completion record */ public function complete($completion) { $this->review($completion, true, true); @@ -92,15 +97,15 @@ class completion_criteria_role extends completion_criteria { /** * Review this criteria and decide if the user has completed - * @access public - * @param object $completion The user's completion record - * @param boolean $mark Optionally set false to not save changes to database - * @return boolean + * + * @param completion_completion $completion The user's completion record + * @param bool $mark Optionally set false to not save changes to database + * @param bool $is_complete Set to false if the criteria has been completed just now. + * @return bool */ public function review($completion, $mark = true, $is_complete = false) { // If we are marking this as complete - if ($is_complete && $mark) - { + if ($is_complete && $mark) { $completion->completedself = 1; $completion->mark_complete(); @@ -112,8 +117,8 @@ class completion_criteria_role extends completion_criteria { /** * Return criteria title for display in reports - * @access public - * @return string + * + * @return string */ public function get_title() { global $DB; @@ -123,8 +128,8 @@ class completion_criteria_role extends completion_criteria { /** * Return a more detailed criteria title for display in reports - * @access public - * @return string + * + * @return string */ public function get_title_detailed() { global $DB; @@ -133,8 +138,8 @@ class completion_criteria_role extends completion_criteria { /** * Return criteria type title for display in reports - * @access public - * @return string + * + * @return string */ public function get_type_title() { return get_string('approval', 'completion'); @@ -142,9 +147,10 @@ class completion_criteria_role extends completion_criteria { /** * Return criteria progress details for display in reports - * @access public - * @param object $completion The user's completion record - * @return array + * + * @param completion_completion $completion The user's completion record + * @return array An array with the following keys: + * type, criteria, requirement, status */ public function get_details($completion) { $details = array(); diff --git a/lib/completion/completion_criteria_self.php b/lib/completion/completion_criteria_self.php index 8dfeb25b6e0..065f00ff45b 100644 --- a/lib/completion/completion_criteria_self.php +++ b/lib/completion/completion_criteria_self.php @@ -1,5 +1,4 @@ - * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @author Aaron Barnes + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ + +defined('MOODLE_INTERNAL') || die(); + +/** + * Course completion critieria - student self marked + * + * @package core_completion + * @category completion + * @copyright 2009 Catalyst IT Ltd + * @author Aaron Barnes + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class completion_criteria_self extends completion_criteria { - /** - * Criteria type constant - * @var int - */ + /* @var int Criteria type constant [COMPLETION_CRITERIA_TYPE_SELF] */ public $criteriatype = COMPLETION_CRITERIA_TYPE_SELF; /** * Finds and returns a data_object instance based on params. - * @static abstract * * @param array $params associative arrays varname=>value - * @return object data_object instance or false if none found. + * @return data_object data_object instance or false if none found. */ public static function fetch($params) { $params['criteriatype'] = COMPLETION_CRITERIA_TYPE_SELF; @@ -45,10 +53,9 @@ class completion_criteria_self extends completion_criteria { /** * Add appropriate form elements to the critieria form - * @access public - * @param object $mform Moodle forms object - * @param mixed $data optional - * @return void + * + * @param moodleform $mform Moodle forms object + * @param stdClass $data Form data */ public function config_form_display(&$mform, $data = null) { $mform->addElement('checkbox', 'criteria_self', get_string('enable')); @@ -60,9 +67,8 @@ class completion_criteria_self extends completion_criteria { /** * Update the criteria information stored in the database - * @access public - * @param array $data Form data - * @return void + * + * @param stdClass $data Form data */ public function update_config(&$data) { if (!empty($data->criteria_self)) { @@ -73,9 +79,8 @@ class completion_criteria_self extends completion_criteria { /** * Mark this criteria as complete - * @access public - * @param object $completion The user's completion record - * @return void + * + * @param completion_completion $completion The user's completion record */ public function complete($completion) { $this->review($completion, true, true); @@ -83,15 +88,15 @@ class completion_criteria_self extends completion_criteria { /** * Review this criteria and decide if the user has completed - * @access public - * @param object $completion The user's completion record - * @param boolean $mark Optionally set false to not save changes to database - * @return boolean + * + * @param completion_completion $completion The user's completion record + * @param bool $mark Optionally set false to not save changes to database + * @param bool $is_complete set true to mark activity complete. + * @return bool */ public function review($completion, $mark = true, $is_complete = false) { // If we are marking this as complete - if ($is_complete && $mark) - { + if ($is_complete && $mark) { $completion->completedself = 1; $completion->mark_complete(); @@ -103,8 +108,8 @@ class completion_criteria_self extends completion_criteria { /** * Return criteria title for display in reports - * @access public - * @return string + * + * @return string */ public function get_title() { return get_string('selfcompletion', 'completion'); @@ -112,8 +117,8 @@ class completion_criteria_self extends completion_criteria { /** * Return a more detailed criteria title for display in reports - * @access public - * @return string + * + * @return string */ public function get_title_detailed() { return $this->get_title(); @@ -121,8 +126,8 @@ class completion_criteria_self extends completion_criteria { /** * Return criteria type title for display in reports - * @access public - * @return string + * + * @return string */ public function get_type_title() { return get_string('self', 'completion'); @@ -130,9 +135,10 @@ class completion_criteria_self extends completion_criteria { /** * Return criteria progress details for display in reports - * @access public - * @param object $completion The user's completion record - * @return array + * + * @param completion_completion $completion The user's completion record + * @return array An array with the following keys: + * type, criteria, requirement, status */ public function get_details($completion) { $details = array(); diff --git a/lib/completion/completion_criteria_unenrol.php b/lib/completion/completion_criteria_unenrol.php index 49e14d71a68..62f30726d18 100644 --- a/lib/completion/completion_criteria_unenrol.php +++ b/lib/completion/completion_criteria_unenrol.php @@ -1,5 +1,4 @@ - * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @author Aaron Barnes + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ + +defined('MOODLE_INTERNAL') || die(); + +/** + * Course completion critieria - completion on unenrolment + * + * @package core_completion + * @category completion + * @copyright 2009 Catalyst IT Ltd + * @author Aaron Barnes + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ class completion_criteria_unenrol extends completion_criteria { - /** - * Criteria type constant - * @var int - */ + /* @var int Criteria type constant [COMPLETION_CRITERIA_TYPE_UNENROL] */ public $criteriatype = COMPLETION_CRITERIA_TYPE_UNENROL; /** * Finds and returns a data_object instance based on params. - * @static abstract * * @param array $params associative arrays varname=>value - * @return object data_object instance or false if none found. + * @return data_object data_object instance or false if none found. */ public static function fetch($params) { $params['criteriatype'] = COMPLETION_CRITERIA_TYPE_UNENROL; @@ -45,10 +53,9 @@ class completion_criteria_unenrol extends completion_criteria { /** * Add appropriate form elements to the critieria form - * @access public - * @param object $mform Moodle forms object - * @param mixed $data optional - * @return void + * + * @param moodleform $mform Moodle forms object + * @param stdClass $data Form data */ public function config_form_display(&$mform, $data = null) { $mform->addElement('checkbox', 'criteria_unenrol', get_string('completiononunenrolment','completion')); @@ -60,9 +67,8 @@ class completion_criteria_unenrol extends completion_criteria { /** * Update the criteria information stored in the database - * @access public - * @param array $data Form data - * @return void + * + * @param stdClass $data Form data */ public function update_config(&$data) { if (!empty($data->criteria_unenrol)) { @@ -73,10 +79,10 @@ class completion_criteria_unenrol extends completion_criteria { /** * Review this criteria and decide if the user has completed - * @access public - * @param object $completion The user's completion record - * @param boolean $mark Optionally set false to not save changes to database - * @return boolean + * + * @param completion_completion $completion The user's completion record + * @param bool $mark Optionally set false to not save changes to database + * @return bool */ public function review($completion, $mark = true) { // Check enrolment @@ -85,8 +91,8 @@ class completion_criteria_unenrol extends completion_criteria { /** * Return criteria title for display in reports - * @access public - * @return string + * + * @return string */ public function get_title() { return get_string('unenrol', 'enrol'); @@ -94,8 +100,8 @@ class completion_criteria_unenrol extends completion_criteria { /** * Return a more detailed criteria title for display in reports - * @access public - * @return string + * + * @return string */ public function get_title_detailed() { return $this->get_title(); @@ -103,8 +109,8 @@ class completion_criteria_unenrol extends completion_criteria { /** * Return criteria type title for display in reports - * @access public - * @return string + * + * @return string */ public function get_type_title() { return get_string('unenrol', 'enrol'); @@ -112,9 +118,10 @@ class completion_criteria_unenrol extends completion_criteria { /** * Return criteria progress details for display in reports - * @access public - * @param object $completion The user's completion record - * @return array + * + * @param completion_completion $completion The user's completion record + * @return array An array with the following keys: + * type, criteria, requirement, status */ public function get_details($completion) { $details = array(); @@ -122,7 +129,6 @@ class completion_criteria_unenrol extends completion_criteria { $details['criteria'] = get_string('unenrolment', 'completion'); $details['requirement'] = get_string('unenrolingfromcourse', 'completion'); $details['status'] = ''; - return $details; } } diff --git a/lib/completion/cron.php b/lib/completion/cron.php index 281a9d76d25..be480d47a21 100644 --- a/lib/completion/cron.php +++ b/lib/completion/cron.php @@ -1,5 +1,4 @@ . - /** * Cron job for reviewing and aggregating course completion criteria * - * @package moodlecore + * @package core_completion + * @category completion * @copyright 2009 Catalyst IT Ltd - * @author Aaron Barnes - * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @author Aaron Barnes + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ -require_once $CFG->libdir.'/completionlib.php'; +defined('MOODLE_INTERNAL') || die(); +require_once($CFG->libdir.'/completionlib.php'); /** * Update user's course completion statuses * - * First update all criteria completions, then - * aggregate all criteria completions and update - * overall course completions - * - * @return void + * First update all criteria completions, then aggregate all criteria completions + * and update overall course completions */ function completion_cron() { @@ -48,7 +45,7 @@ function completion_cron() { /** * Mark users as started if the config option is set * - * @return void + * @return void */ function completion_cron_mark_started() { global $CFG, $DB; @@ -200,7 +197,7 @@ function completion_cron_mark_started() { * Loop through each installed criteria and run the * cron() method if it exists * - * @return void + * @return void */ function completion_cron_criteria() { @@ -227,8 +224,6 @@ function completion_cron_criteria() { /** * Aggregate each user's criteria completions - * - * @return void */ function completion_cron_completions() { global $DB; @@ -394,7 +389,6 @@ function completion_cron_completions() { * @param int $method COMPLETION_AGGREGATION_* constant * @param bool $data Criteria completion status * @param bool|null $state Aggregation state - * @return void */ function completion_cron_aggregate($method, $data, &$state) { if ($method == COMPLETION_AGGREGATION_ALL) { diff --git a/lib/completion/data_object.php b/lib/completion/data_object.php index c096c8e8bf4..01345ee0cc9 100644 --- a/lib/completion/data_object.php +++ b/lib/completion/data_object.php @@ -1,65 +1,66 @@ . -/////////////////////////////////////////////////////////////////////////// -// // -// NOTICE OF COPYRIGHT // -// // -// Moodle - Modular Object-Oriented Dynamic Learning Environment // -// http://moodle.com // -// // -// Copyright (C) 1999 onwards Martin Dougiamas http://dougiamas.com // -// // -// This program 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 2 of the License, or // -// (at your option) any later version. // -// // -// This program 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: // -// // -// http://www.gnu.org/copyleft/gpl.html // -// // -/////////////////////////////////////////////////////////////////////////// +/** + * Course completion critieria aggregation + * + * @package core_completion + * @category completion + * @copyright 2009 Catalyst IT Ltd + * @author Aaron Barnes + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ + +defined('MOODLE_INTERNAL') || die(); /** * A data abstraction object that holds methods and attributes - * @abstract + * + * @package core_completion + * @category completion + * @copyright 2009 Catalyst IT Ltd + * @author Aaron Barnes + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ abstract class data_object { - /** - * Table that the class maps to in the database - * @var string $table - */ + + /* @var string Table that the class maps to in the database */ public $table; - /** - * Array of required table fields, must start with 'id'. - * @var array $required_fields - */ + /* @var array Array of required table fields, must start with 'id'. */ public $required_fields = array('id'); /** * Array of optional fields with default values - usually long text information that is not always needed. * If you want to create an instance without optional fields use: new data_object($only_required_fields, false); - * @var array $optional_fields + * @var array */ public $optional_fields = array(); - /** - * The PK. - * @var int $id - */ + /* @var int The primary key */ public $id; /** * Constructor. Optionally (and by default) attempts to fetch corresponding row from DB. + * * @param array $params an array with required parameters for this data object. - * @param boolean $fetch Whether to fetch corresponding row from DB or not, + * @param bool $fetch Whether to fetch corresponding row from DB or not, * optional fields might not be defined if false used */ - public function __construct($params=NULL, $fetch=true) { + public function __construct($params = null, $fetch = true) { if (!empty($params) and (is_array($params) or is_object($params))) { if ($fetch) { if ($data = $this->fetch($params)) { @@ -80,6 +81,7 @@ abstract class data_object { /** * Makes sure all the optional fields are loaded. + * * If id present (==instance exists in db) fetches data from db. * Defaults are used for new instances. */ @@ -99,10 +101,12 @@ abstract class data_object { /** * Finds and returns a data_object instance based on params. - * @static abstract * - * @param array $params associative arrays varname=>value - * @return object data_object instance or false if none found. + * This function MUST be overridden by all deriving classes. + * + * @param array $params associative arrays varname => value + * @throws coding_exception This function MUST be overridden + * @return data_object instance of data_object or false if none found. */ public static function fetch($params) { throw new coding_exception('fetch() method needs to be overridden in each subclass of data_object'); @@ -111,7 +115,10 @@ abstract class data_object { /** * Finds and returns all data_object instances based on params. * - * @param array $params associative arrays varname=>value + * This function MUST be overridden by all deriving classes. + * + * @param array $params associative arrays varname => value + * @throws coding_exception This function MUST be overridden * @return array array of data_object instances or false if none found. */ public static function fetch_all($params) { @@ -120,8 +127,12 @@ abstract class data_object { /** * Factory method - uses the parameters to retrieve matching instance from the DB. - * @static final protected - * @return mixed object instance or false if not found + * + * @final + * @param string $table The table name to fetch from + * @param string $classname The class that you want the result instantiated as + * @param array $params Any params required to select the desired row + * @return object Instance of $classname or false. */ protected static function fetch_helper($table, $classname, $params) { if ($instances = self::fetch_all_helper($table, $classname, $params)) { @@ -137,7 +148,11 @@ abstract class data_object { /** * Factory method - uses the parameters to retrieve all matching instances from the DB. - * @static final protected + * + * @final + * @param string $table The table name to fetch from + * @param string $classname The class that you want the result instantiated as + * @param array $params Any params required to select the desired row * @return mixed array of object instances or false if not found */ public static function fetch_all_helper($table, $classname, $params) { @@ -185,7 +200,8 @@ abstract class data_object { /** * Updates this object in the Database, based on its object variables. ID must be set. - * @return boolean success + * + * @return bool success */ public function update() { global $DB; @@ -205,7 +221,8 @@ abstract class data_object { /** * Deletes this object from the database. - * @return boolean success + * + * @return bool success */ public function delete() { global $DB; @@ -228,6 +245,8 @@ abstract class data_object { /** * Returns object with fields and values that are defined in database + * + * @return stdClass */ public function get_record_data() { $data = new stdClass(); @@ -248,6 +267,7 @@ abstract class data_object { * Records this object in the Database, sets its id to the returned value, and returns that value. * If successful this function also fetches the new object data from database and stores it * in object properties. + * * @return int PK ID if successful, false otherwise */ public function insert() { @@ -274,6 +294,8 @@ abstract class data_object { * each variable in turn. If the DB has different data, the db's data is used to update * the object. This is different from the update() function, which acts on the DB record * based on the object. + * + * @return bool True for success, false otherwise. */ public function update_from_db() { if (empty($this->id)) { @@ -294,7 +316,10 @@ abstract class data_object { /** * Given an associated array or object, cycles through each key/variable * and assigns the value to the corresponding variable in this object. - * @static final + * + * @final + * @param data_object $instance + * @param array $params */ public static function set_properties(&$instance, $params) { $params = (array) $params; @@ -310,8 +335,8 @@ abstract class data_object { * deleted in the database. Default does nothing, can be overridden to * hook in special behaviour. * - * @param bool $deleted + * @param bool $deleted Set this to true if it has been deleted. */ - function notify_changed($deleted) { + public function notify_changed($deleted) { } -} +} \ No newline at end of file diff --git a/lib/completionlib.php b/lib/completionlib.php index b8d9df60495..a5086f83194 100644 --- a/lib/completionlib.php +++ b/lib/completionlib.php @@ -1,5 +1,4 @@ . /** - * Contains a class used for tracking whether activities have been completed - * by students ('completion') + * Contains classes, functions and constants used during the tracking + * of activity completion for users. * * Completion top-level options (admin setting enablecompletion) * - * @package core - * @subpackage completion - * @copyright 1999 onwards Martin Dougiamas {@link http://moodle.com} - * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @package core_completion + * @category completion + * @copyright 1999 onwards Martin Dougiamas {@link http://moodle.com} + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ defined('MOODLE_INTERNAL') || die(); +/** + * Include the required completion libraries + */ require_once $CFG->libdir.'/completion/completion_aggregation.php'; require_once $CFG->libdir.'/completion/completion_criteria.php'; require_once $CFG->libdir.'/completion/completion_completion.php'; require_once $CFG->libdir.'/completion/completion_criteria_completion.php'; -/** The completion system is enabled in this site/course */ +/** + * The completion system is enabled in this site/course + */ define('COMPLETION_ENABLED', 1); -/** The completion system is not enabled in this site/course */ +/** + * The completion system is not enabled in this site/course + */ define('COMPLETION_DISABLED', 0); -// Completion tracking options per-activity (course_modules/completion) - -/** Completion tracking is disabled for this activity */ +/** + * Completion tracking is disabled for this activity + * This is a completion tracking option per-activity (course_modules/completion) + */ define('COMPLETION_TRACKING_NONE', 0); -/** Manual completion tracking (user ticks box) is enabled for this activity */ + +/** + * Manual completion tracking (user ticks box) is enabled for this activity + * This is a completion tracking option per-activity (course_modules/completion) + */ define('COMPLETION_TRACKING_MANUAL', 1); -/** Automatic completion tracking (system ticks box) is enabled for this activity */ +/** + * Automatic completion tracking (system ticks box) is enabled for this activity + * This is a completion tracking option per-activity (course_modules/completion) + */ define('COMPLETION_TRACKING_AUTOMATIC', 2); -// Completion state values (course_modules_completion/completionstate) - -/** The user has not completed this activity. */ +/** + * The user has not completed this activity. + * This is a completion state value (course_modules_completion/completionstate) + */ define('COMPLETION_INCOMPLETE', 0); -/** The user has completed this activity. It is not specified whether they have - * passed or failed it. */ +/** + * The user has completed this activity. It is not specified whether they have + * passed or failed it. + * This is a completion state value (course_modules_completion/completionstate) + */ define('COMPLETION_COMPLETE', 1); -/** The user has completed this activity with a grade above the pass mark. */ +/** + * The user has completed this activity with a grade above the pass mark. + * This is a completion state value (course_modules_completion/completionstate) + */ define('COMPLETION_COMPLETE_PASS', 2); -/** The user has completed this activity but their grade is less than the pass mark */ +/** + * The user has completed this activity but their grade is less than the pass mark + * This is a completion state value (course_modules_completion/completionstate) + */ define('COMPLETION_COMPLETE_FAIL', 3); -// Completion effect changes (used only in update_state) - -/** The effect of this change to completion status is unknown. */ +/** + * The effect of this change to completion status is unknown. + * A completion effect changes (used only in update_state) + */ define('COMPLETION_UNKNOWN', -1); -/** The user's grade has changed, so their new state might be - * COMPLETION_COMPLETE_PASS or COMPLETION_COMPLETE_FAIL. */ -// TODO Is this useful? +/** + * The user's grade has changed, so their new state might be + * COMPLETION_COMPLETE_PASS or COMPLETION_COMPLETE_FAIL. + * A completion effect changes (used only in update_state) + */ define('COMPLETION_GRADECHANGE', -2); -// Whether view is required to create an activity (course_modules/completionview) - -/** User must view this activity */ +/** + * User must view this activity. + * Whether view is required to create an activity (course_modules/completionview) + */ define('COMPLETION_VIEW_REQUIRED', 1); -/** User does not need to view this activity */ +/** + * User does not need to view this activity + * Whether view is required to create an activity (course_modules/completionview) + */ define('COMPLETION_VIEW_NOT_REQUIRED', 0); -// Completion viewed state (course_modules_completion/viewed) - -/** User has viewed this activity */ +/** + * User has viewed this activity. + * Completion viewed state (course_modules_completion/viewed) + */ define('COMPLETION_VIEWED', 1); -/** User has not viewed this activity */ +/** + * User has not viewed this activity. + * Completion viewed state (course_modules_completion/viewed) + */ define('COMPLETION_NOT_VIEWED', 0); -// Completion cacheing - -/** Cache expiry time in seconds (10 minutes) */ +/** + * Cache expiry time in seconds (10 minutes) + * Completion cacheing + */ define('COMPLETION_CACHE_EXPIRY', 10*60); -// Combining completion condition. This is also the value you should return -// if you don't have any applicable conditions. Used for activity completion. -/** Completion details should be ORed together and you should return false if - none apply */ +/** + * Completion details should be ORed together and you should return false if + * none apply. + */ define('COMPLETION_OR', false); -/** Completion details should be ANDed together and you should return true if - none apply */ +/** + * Completion details should be ANDed together and you should return true if + * none apply + */ define('COMPLETION_AND', true); -// Course completion criteria aggregation methods -define('COMPLETION_AGGREGATION_ALL', 1); -define('COMPLETION_AGGREGATION_ANY', 2); +/** + * Course completion criteria aggregation method. + */ +define('COMPLETION_AGGREGATION_ALL', 1); +/** + * Course completion criteria aggregation method. + */ +define('COMPLETION_AGGREGATION_ANY', 2); /** @@ -109,48 +152,40 @@ define('COMPLETION_AGGREGATION_ANY', 2); * Does not contain any data, so you can safely construct it multiple times * without causing any problems. * + * @package core + * @category completion + * @copyright 2008 Sam Marshall * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later - * @package moodlecore */ class completion_info { - /** - * Course object passed during construction - * @access private - * @var object - */ + + /* @var stdClass Course object passed during construction */ private $course; - /** - * Course id - * @access public - * @var int - */ + /* @var int Course id */ public $course_id; - /** - * Completion criteria - * @access private - * @var array - * @see completion_info->get_criteria() - */ + /* @var array Completion criteria {@link completion_info::get_criteria()} */ private $criteria; /** * Return array of aggregation methods - * @access public - * @return array + * @return array */ public static function get_aggregation_methods() { return array( - COMPLETION_AGGREGATION_ALL => get_string('all'), - COMPLETION_AGGREGATION_ANY => get_string('any', 'completion'), + COMPLETION_AGGREGATION_ALL => get_string('all'), + COMPLETION_AGGREGATION_ANY => get_string('any', 'completion'), ); } /** * Constructs with course details. * - * @param object $course Moodle course object. Must have at least ->id, ->enablecompletion + * When instantiating a new completion info object you must provide a course + * object with at least id, and enablecompletion properties. + * + * @param stdClass $course Moodle course object. */ public function __construct($course) { $this->course = $course; @@ -160,10 +195,7 @@ class completion_info { /** * Determines whether completion is enabled across entire site. * - * Static function. - * - * @global object - * @return int COMPLETION_ENABLED (true) if completion is enabled for the site, + * @return bool COMPLETION_ENABLED (true) if completion is enabled for the site, * COMPLETION_DISABLED (false) if it's complete */ public static function is_enabled_for_site() { @@ -175,16 +207,13 @@ class completion_info { * Checks whether completion is enabled in a particular course and possibly * activity. * - * @global object - * @uses COMPLETION_DISABLED - * @uses COMPLETION_ENABLED - * @param object $cm Course-module object. If not specified, returns the course + * @param stdClass|cm_info $cm Course-module object. If not specified, returns the course * completion enable state. * @return mixed COMPLETION_ENABLED or COMPLETION_DISABLED (==0) in the case of * site and course; COMPLETION_TRACKING_MANUAL, _AUTOMATIC or _NONE (==0) * for a course-module. */ - public function is_enabled($cm=null) { + public function is_enabled($cm = null) { global $CFG, $DB; // First check global completion @@ -214,8 +243,8 @@ class completion_info { /** * Displays the 'Your progress' help icon, if completion tracking is enabled. * Just prints the result of display_help_icon(). - * @deprecated Use display_help_icon instead. - * @return void + * + * @deprecated since Moodle 2.0 - Use display_help_icon instead. */ public function print_help_icon() { print $this->display_help_icon(); @@ -223,7 +252,7 @@ class completion_info { /** * Returns the 'Your progress' help icon, if completion tracking is enabled. - * @global object + * * @return string HTML code for help icon, or blank if not needed */ public function display_help_icon() { @@ -239,10 +268,10 @@ class completion_info { /** * Get a course completion for a user - * @access public - * @param $user_id int User id - * @param $criteriatype int Specific criteria type to return - * @return false|completion_criteria_completion + * + * @param int $user_id User id + * @param int $criteriatype Specific criteria type to return + * @return bool|completion_criteria_completion returns false on fail */ public function get_completion($user_id, $criteriatype) { $completions = $this->get_completions($user_id, $criteriatype); @@ -258,10 +287,10 @@ class completion_info { /** * Get all course criteria's completion objects for a user - * @access public - * @param $user_id int User id - * @param $criteriatype int optional Specific criteria type to return - * @return array + * + * @param int $user_id User id + * @param int $criteriatype Specific criteria type to return (optional) + * @return array */ public function get_completions($user_id, $criteriatype = null) { $criterion = $this->get_criteria($criteriatype); @@ -286,10 +315,10 @@ class completion_info { /** * Get completion object for a user and a criteria - * @access public - * @param $user_id int User id - * @param $criteria completion_criteria Criteria object - * @return completion_criteria_completion + * + * @param int $user_id User id + * @param completion_criteria $criteria Criteria object + * @return completion_criteria_completion */ public function get_user_completion($user_id, $criteria) { $params = array( @@ -304,8 +333,7 @@ class completion_info { /** * Check if course has completion criteria set * - * @access public - * @return bool + * @return bool Returns true if there are criteria */ public function has_criteria() { $criteria = $this->get_criteria(); @@ -313,12 +341,10 @@ class completion_info { return (bool) count($criteria); } - /** * Get course completion criteria - * @access public - * @param $criteriatype int optional Specific criteria type to return - * @return void + * + * @param int $criteriatype Specific criteria type to return (optional) */ public function get_criteria($criteriatype = null) { @@ -361,9 +387,9 @@ class completion_info { /** * Get aggregation method - * @access public - * @param $criteriatype int optional If none supplied, get overall aggregation method - * @return int + * + * @param int $criteriatype If none supplied, get overall aggregation method (optional) + * @return int One of COMPLETION_AGGREGATION_ALL or COMPLETION_AGGREGATION_ANY */ public function get_aggregation_method($criteriatype = null) { $params = array( @@ -382,8 +408,8 @@ class completion_info { /** * Get incomplete course completion criteria - * @access public - * @return void + * + * @return array */ public function get_incomplete_criteria() { $incomplete = array(); @@ -410,9 +436,9 @@ class completion_info { /** * Has the supplied user completed this course - * @access public - * @param $user_id int User's id - * @return boolean + * + * @param int $user_id User's id + * @return boolean */ public function is_course_complete($user_id) { $params = array( @@ -441,14 +467,7 @@ class completion_info { * calling the involved module via modulename_get_completion_state() to check * module-specific conditions. * - * @global object - * @global object - * @uses COMPLETION_COMPLETE - * @uses COMPLETION_INCOMPLETE - * @uses COMPLETION_COMPLETE_PASS - * @uses COMPLETION_COMPLETE_FAIL - * @uses COMPLETION_TRACKING_MANUAL - * @param object $cm Course-module + * @param stdClass|cm $cm_info Course-module * @param int $possibleresult Expected completion result. If the event that * has just occurred (e.g. add post) can only result in making the activity * complete when it wasn't before, use COMPLETION_COMPLETE. If the event that @@ -510,21 +529,12 @@ class completion_info { * * Internal function. Not private, so we can unit-test it. * - * @global object - * @global object - * @global object - * @uses COMPLETION_VIEW_REQUIRED - * @uses COMPLETION_NOT_VIEWED - * @uses COMPLETION_INCOMPLETE - * @uses FEATURE_COMPLETION_HAS_RULES - * @uses COMPLETION_COMPLETE - * @uses COMPLETION_AND - * @param object $cm Activity + * @param stdClass|cm_info $cm Activity * @param int $userid ID of user - * @param object $current Previous completion information from database + * @param stdClass $current Previous completion information from database * @return mixed */ - function internal_get_state($cm, $userid, $current) { + public function internal_get_state($cm, $userid, $current) { global $USER, $DB, $CFG; // Get user ID @@ -590,7 +600,6 @@ class completion_info { } - /** * Marks a module as viewed. * @@ -600,10 +609,8 @@ class completion_info { * Note that this function must be called before you print the page header because * it is possible that the navigation block may depend on it. If you call it after * printing the header, it shows a developer debug warning. - * @uses COMPLETION_VIEW_NOT_REQUIRED - * @uses COMPLETION_VIEWED - * @uses COMPLETION_COMPLETE - * @param object $cm Activity + * + * @param stdClass|cm_info $cm Activity * @param int $userid User ID or 0 (default) for current user * @return void */ @@ -634,8 +641,7 @@ class completion_info { * deciding whether completion information should be 'locked' in the module * editing form. * - * @global object - * @param object $cm Activity + * @param cm_info $cm Activity * @return int The number of users who have completion data stored for this * activity, 0 if none */ @@ -656,10 +662,9 @@ class completion_info { * deciding whether completion information should be 'locked' in the completion * settings form and activity completion settings. * - * @global object - * @param int $user_id Optionally only get course completion data for a single user + * @param int $user_id Optionally only get course completion data for a single user * @return int The number of users who have completion data stored for this - * course, 0 if none + * course, 0 if none */ public function count_course_user_data($user_id = null) { global $DB; @@ -687,7 +692,7 @@ class completion_info { /** * Check if this course's completion criteria should be locked * - * @return boolean + * @return boolean */ public function is_course_locked() { return (bool) $this->count_course_user_data(); @@ -697,9 +702,6 @@ class completion_info { * Deletes all course completion completion data. * * Intended to be used when unlocking completion criteria settings. - * - * @global object - * @return void */ public function delete_course_completion_data() { global $DB; @@ -713,9 +715,7 @@ class completion_info { * * Intended for use only when the activity itself is deleted. * - * @global object - * @global object - * @param object $cm Activity + * @param stdClass|cm_info $cm Activity */ public function delete_all_state($cm) { global $SESSION, $DB; @@ -738,7 +738,7 @@ class completion_info { if ($criterion->moduleinstance == $cm->id) { $acriteria = $criterion; break; - } + } } if ($acriteria) { @@ -759,10 +759,7 @@ class completion_info { * Resetting state of manual tickbox has same result as deleting state for * it. * - * @global object - * @uses COMPLETION_TRACKING_MANUAL - * @uses COMPLETION_UNKNOWN - * @param object $cm Activity + * @param stcClass|cm_info $cm Activity */ public function reset_all_state($cm) { global $DB; @@ -799,12 +796,7 @@ class completion_info { * Obtains completion data for a particular activity and user (from the * session cache if available, or by SQL query) * - * @global object - * @global object - * @global object - * @global object - * @uses COMPLETION_CACHE_EXPIRY - * @param object $cm Activity; only required field is ->id + * @param stcClass|cm_info $cm Activity; only required field is ->id * @param bool $wholecourse If true (default false) then, when necessary to * fill the cache, retrieves information from the entire course not just for * this one activity @@ -815,7 +807,7 @@ class completion_info { * Otherwise the method calls get_fast_modinfo itself. * @return object Completion data (record from course_modules_completion) */ - public function get_data($cm, $wholecourse=false, $userid=0, $modinfo=null) { + public function get_data($cm, $wholecourse = false, $userid = 0, $modinfo = null) { global $USER, $CFG, $SESSION, $DB; // Get user ID @@ -926,13 +918,10 @@ class completion_info { * * (Internal function. Not private, so we can unit-test it.) * - * @global object - * @global object - * @global object - * @param object $cm Activity - * @param object $data Data about completion for that user + * @param stdClass|cm_info $cm Activity + * @param stdClass $data Data about completion for that user */ - function internal_set_data($cm, $data) { + public function internal_set_data($cm, $data) { global $USER, $SESSION, $DB; $transaction = $DB->start_delegated_transaction(); @@ -961,8 +950,6 @@ class completion_info { * Obtains a list of activities for which completion is enabled on the * course. The list is ordered by the section order of those activities. * - * @global object - * @uses COMPLETION_TRACKING_NONE * @param array $modinfo For unit testing only, supply the value * here. Otherwise the method calls get_fast_modinfo * @return array Array from $cmid => $cm of all activities with completion enabled, @@ -996,15 +983,14 @@ class completion_info { return $result; } - /** * Checks to see if the userid supplied has a tracked role in * this course * - * @param $userid User id - * @return bool + * @param int $userid User id + * @return bool */ - function is_tracked_user($userid) { + public function is_tracked_user($userid) { global $DB; $tracked = $this->generate_tracked_user_sql(); @@ -1018,18 +1004,17 @@ class completion_info { return $DB->record_exists_sql($sql, $params); } - /** * Return number of users whose progress is tracked in this course * * Optionally supply a search's where clause, or a group id * - * @param string $where Where clause sql - * @param array $where_params Where clause params - * @param int $groupid Group id - * @return int + * @param string $where Where clause sql + * @param array $where_params Where clause params + * @param int $groupid Group id + * @return int */ - function get_num_tracked_users($where = '', $where_params = array(), $groupid = 0) { + public function get_num_tracked_users($where = '', $where_params = array(), $groupid = 0) { global $DB; $tracked = $this->generate_tracked_user_sql($groupid); @@ -1045,23 +1030,22 @@ class completion_info { return $DB->count_records_sql($sql, $params); } - /** * Return array of users whose progress is tracked in this course * * Optionally supply a search's where caluse, group id, sorting, paging * - * @param string $where Where clause sql (optional) - * @param array $where_params Where clause params (optional) - * @param integer $groupid Group ID to restrict to (optional) - * @param string $sort Order by clause (optional) - * @param integer $limitfrom Result start (optional) - * @param integer $limitnum Result max size (optional) + * @param string $where Where clause sql (optional) + * @param array $where_params Where clause params (optional) + * @param integer $groupid Group ID to restrict to (optional) + * @param string $sort Order by clause (optional) + * @param integer $limitfrom Result start (optional) + * @param integer $limitnum Result max size (optional) * @param context $extracontext If set, includes extra user information fields * as appropriate to display for current user in this context - * @return array + * @return array */ - function get_tracked_users($where = '', $where_params = array(), $groupid = 0, + public function get_tracked_users($where = '', $where_params = array(), $groupid = 0, $sort = '', $limitfrom = '', $limitnum = '', context $extracontext = null) { global $DB; @@ -1095,17 +1079,16 @@ class completion_info { return $users ? $users : array(); // In case it returns false } - /** * Generate the SQL for finding tracked users in this course * * Returns an object containing the sql fragment and an array of * bound data params. * - * @param integer $groupid - * @return object + * @param integer $groupid + * @return stdClass With two properties, sql (string), and data (array) */ - function generate_tracked_user_sql($groupid = 0) { + public function generate_tracked_user_sql($groupid = 0) { global $CFG; $return = new stdClass(); @@ -1186,8 +1169,6 @@ class completion_info { * Users are included (in the first array) even if they do not have * completion progress for any course-module. * - * @global object - * @global object * @param bool $sortfirstname If true, sort by first name, otherwise sort by * last name * @param string $where Where clause sql (optional) @@ -1197,7 +1178,7 @@ class completion_info { * @param int $start User to start at if paging (optional) * @param context $extracontext If set, includes extra user information fields * as appropriate to display for current user in this context - * @return Object with ->total and ->start (same as $start) and ->users; + * @return stdClass with ->total and ->start (same as $start) and ->users; * an array of user objects (like mdl_user id, firstname, lastname) * containing an additional ->progress array of coursemoduleid => completionstate */ @@ -1231,8 +1212,7 @@ class completion_info { {course_modules} cm INNER JOIN {course_modules_completion} cmc ON cm.id=cmc.coursemoduleid WHERE - cm.course=? AND cmc.userid $insql - ", $params); + cm.course=? AND cmc.userid $insql", $params); foreach ($rs as $progress) { $progress = (object)$progress; $results[$progress->userid]->progress[$progress->coursemoduleid] = $progress; @@ -1248,13 +1228,10 @@ class completion_info { * been changed. If the changed grade is used to determine completion for * the course-module, then the completion status will be updated. * - * @uses COMPLETION_TRACKING_MANUAL - * @uses COMPLETION_INCOMPLETE - * @param object $cm Course-module for item that owns grade + * @param stdClass|cm_info $cm Course-module for item that owns grade * @param grade_item $item Grade item - * @param object $grade + * @param stdClass $grade * @param bool $deleted - * @return void */ public function inform_grade_changed($cm, $item, $grade, $deleted) { // Bail out now if completion is not enabled for course-module, it is enabled @@ -1286,15 +1263,11 @@ class completion_info { * * Internal function. Not private, so we can unit-test it. * - * @uses COMPLETION_INCOMPLETE - * @uses COMPLETION_COMPLETE_PASS - * @uses COMPLETION_COMPLETE_FAIL - * @uses COMPLETION_COMPLETE - * @param object $item grade_item - * @param object $grade grade_grade + * @param grade_item $item an instance of grade_item + * @param grade_grade $grade an instance of grade_grade * @return int Completion state e.g. COMPLETION_INCOMPLETE */ - function internal_get_grade_state($item, $grade) { + public function internal_get_grade_state($item, $grade) { if (!$grade) { return COMPLETION_INCOMPLETE; } @@ -1327,12 +1300,11 @@ class completion_info { * This is to be used only for system errors (things that shouldn't happen) * and not user-level errors. * - * @global object - * @param string $error Error string (will not be displayed to user unless - * debugging is enabled) - * @return void Throws moodle_exception Exception with the error string as debug info + * @global type $CFG + * @param string $error Error string (will not be displayed to user unless debugging is enabled) + * @throws moodle_exception Exception with the error string as debug info */ - function internal_systemerror($error) { + public function internal_systemerror($error) { global $CFG; throw new moodle_exception('err_system','completion', $CFG->wwwroot.'/course/view.php?id='.$this->course->id,null,$error); @@ -1340,12 +1312,10 @@ class completion_info { /** * For testing only. Wipes information cached in user session. - * - * @global object */ - static function wipe_session_cache() { + public static function wipe_session_cache() { global $SESSION; unset($SESSION->completioncache); unset($SESSION->completioncacheuserid); } -} +} \ No newline at end of file