From 28f672b2df0cc7974e040337539db9c4035043b6 Mon Sep 17 00:00:00 2001 From: samhemelryk Date: Thu, 28 May 2009 05:30:46 +0000 Subject: [PATCH] mod lib MDL-19294 Added boilerplate and phpdocs --- mod/resource/lib.php | 311 +++++++++++++++++++++++++++++++++++++------ mod/scorm/lib.php | 215 ++++++++++++++++++++++-------- 2 files changed, 427 insertions(+), 99 deletions(-) diff --git a/mod/resource/lib.php b/mod/resource/lib.php index b18ba14132..b54bfb0914 100644 --- a/mod/resource/lib.php +++ b/mod/resource/lib.php @@ -1,9 +1,36 @@ -. +/** + * @package mod-resource + * @copyright 1999 onwards Martin Dougiamas {@link http://moodle.com} + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ + +/** Require {@link portfoliolib.php} */ require_once($CFG->libdir.'/portfoliolib.php'); +/** RESOURCE_LOCALPATH = LOCALPATH */ define('RESOURCE_LOCALPATH', 'LOCALPATH'); +/** + * @global array $RESOURCE_WINDOW_OPTIONS + * @name $RESOURCE_WINDOW_OPTIONS + */ global $RESOURCE_WINDOW_OPTIONS; // must be global because it might be included from a function! $RESOURCE_WINDOW_OPTIONS = array('resizable', 'scrollbars', 'directories', 'location', 'menubar', 'toolbar', 'status', 'width', 'height'); @@ -13,11 +40,13 @@ if (!isset($CFG->resource_hide_repository)) { } /** -* resource_base is the base class for resource types -* -* This class provides all the functionality for a resource -*/ - + * resource_base is the base class for resource types + * + * This class provides all the functionality for a resource + * @package mod-resource + * @copyright 1999 onwards Martin Dougiamas {@link http://moodle.com} + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ class resource_base { var $cm; @@ -26,14 +55,18 @@ class resource_base { var $navlinks; /** - * Constructor for the base resource class - * - * Constructor for the base resource class. - * If cmid is set create the cm, course, resource objects. - * and do some checks to make sure people can be here, and so on. - * - * @param cmid integer, the current course module id - not set for new resources - */ + * Constructor for the base resource class + * + * Constructor for the base resource class. + * If cmid is set create the cm, course, resource objects. + * and do some checks to make sure people can be here, and so on. + * + * @global stdClass + * @global object + * @global object + * @uses CONTEXT_MODULE + * @param int $cmid the current course module id - not set for new resources + */ function resource_base($cmid=0) { global $CFG, $COURSE, $DB; @@ -78,8 +111,14 @@ class resource_base { /** - * Display the resource with the course blocks. - */ + * Display the resource with the course blocks. + * + * @global stdClass + * @uses PAGE_COURSE_VIEW + * @uses PARAM_BOOL + * @uses BLOCK_POS_LEFT + * @uses BLOCK_POS_RIGHT + */ function display_course_blocks_start() { global $CFG, $USER, $THEME; @@ -147,6 +186,11 @@ class resource_base { /** * Finish displaying the resource with the course blocks + * + * @global stdClass + * @global object + * @uses BLOCK_POS_LEFT + * @uses BLOCK_POS_RIGHT */ function display_course_blocks_end() { global $CFG, $THEME; @@ -199,25 +243,35 @@ class resource_base { } - + /** + * Given an object containing all the necessary data, + * (defined by the form in mod_form.php) this function + * will create a new instance and return the id number + * of the new instance. + * + * @global object + * @param object $resource + * @return int|bool + */ function add_instance($resource) { global $DB; - // Given an object containing all the necessary data, - // (defined by the form in mod_form.php) this function - // will create a new instance and return the id number - // of the new instance. $resource->timemodified = time(); return $DB->insert_record("resource", $resource); } - + /** + * Given an object containing all the necessary data, + * (defined by the form in mod_form.php) this function + * will update an existing instance with new data. + * + * @global object + * @param object $resource + * @return bool + */ function update_instance($resource) { global $DB; - // Given an object containing all the necessary data, - // (defined by the form in mod_form.php) this function - // will update an existing instance with new data. $resource->id = $resource->instance; $resource->timemodified = time(); @@ -225,12 +279,17 @@ class resource_base { return $DB->update_record("resource", $resource); } - + /** + * Given an object containing the resource data + * this function will permanently delete the instance + * and any data that depends on it. + * + * @global object + * @param object $resource + * @return bool + */ function delete_instance($resource) { global $DB; - // Given an object containing the resource data - // this function will permanently delete the instance - // and any data that depends on it. $result = true; @@ -241,19 +300,35 @@ class resource_base { return $result; } + /** + * + */ function setup_elements(&$mform) { //override to add your own options } + /** + * + */ function setup_preprocessing(&$default_values){ //override to add your own options } + /** + * @todo penny implement later - see MDL-15758 + */ function portfolio_prepare_package_uploaded($exporter) { // @todo penny implement later - see MDL-15758 } + /** + * @uses FORMAT_MOODLE + * @uses FORMAT_HTML + * @param object $exporter + * @param bool $text + * @return int|bool + */ function portfolio_prepare_package_online($exporter, $text=false) { $filename = clean_filename($this->cm->name . '.' . 'html'); $formatoptions = (object)array('noclean' => true); @@ -262,6 +337,12 @@ class resource_base { return $exporter->write_new_file($content, $filename, false); } + /** + * @param bool $text + * @uses FORMAT_MOODLE + * @uses FORMAT_HTML + * @return string + */ function portfolio_get_sha1_online($text=false) { $formatoptions = (object)array('noclean' => true); $format = (($text) ? FORMAT_MOODLE : FORMAT_HTML); @@ -269,6 +350,9 @@ class resource_base { return sha1($content); } + /** + * @todo penny implement later. + */ function portfolio_get_sha1_uploaded() { // @todo penny implement later. } @@ -276,7 +360,12 @@ class resource_base { } /// end of class definition - +/** + * @global stdClass + * @uses PARAM_SAFEDIR + * @param object $resource + * @return int|bool + */ function resource_add_instance($resource) { global $CFG; @@ -289,6 +378,12 @@ function resource_add_instance($resource) { return $res->add_instance($resource); } +/** + * @global stdClass + * @uses PARAM_SAFEDIR + * @param object $resource + * @return bool + */ function resource_update_instance($resource) { global $CFG; @@ -301,6 +396,13 @@ function resource_update_instance($resource) { return $res->update_instance($resource); } +/** + * @global stdClass + * @global object + * @uses PARAM_SAFEDIR + * @param int $id + * @return bool + */ function resource_delete_instance($id) { global $CFG, $DB; @@ -317,7 +419,15 @@ function resource_delete_instance($id) { return $res->delete_instance($resource); } - +/** + * + * @global object + * @param object $course + * @param object $user + * @param object $mod + * @param object $resource + * @return object|null + */ function resource_user_outline($course, $user, $mod, $resource) { global $DB; @@ -336,7 +446,14 @@ function resource_user_outline($course, $user, $mod, $resource) { return NULL; } - +/** + * @global stdClass + * @global object + * @param object $course + * @param object $user + * @param object $mod + * @param object $resource + */ function resource_user_complete($course, $user, $mod, $resource) { global $CFG, $DB; @@ -355,20 +472,30 @@ function resource_user_complete($course, $user, $mod, $resource) { } } +/** + * Returns the users with data in one resource + * (NONE, byt must exists on EVERY mod !!) + * + * @param int $resourceid + * @return bool false + */ function resource_get_participants($resourceid) { -//Returns the users with data in one resource -//(NONE, byt must exists on EVERY mod !!) - return false; } +/** + * Given a course_module object, this function returns any + * "extra" information that may be needed when printing + * this activity in a course listing. + * + * See {@link get_array_of_activities()} in course/lib.php + * + * @global stdClass + * @global object + * @param object $coursemodule + * @return object info + */ function resource_get_coursemodule_info($coursemodule) { -/// Given a course_module object, this function returns any -/// "extra" information that may be needed when printing -/// this activity in a course listing. -/// -/// See get_array_of_activities() in course/lib.php -/// global $CFG, $DB; $info = NULL; @@ -403,6 +530,14 @@ function resource_get_coursemodule_info($coursemodule) { return $info; } +/** + * @param string $text + * @param string $url + * @param string $tagtoparse + * @param string $keytoparse + * @param string $prefix + * @return string + */ function resource_redirect_tags($text, $url, $tagtoparse, $keytoparse,$prefix = "" ) { $valid = 1; if ( strpos($url,"?") == FALSE ) { @@ -491,6 +626,10 @@ function resource_redirect_tags($text, $url, $tagtoparse, $keytoparse,$prefix = return $text; } +/** + * @param string $path + * @return bool + */ function resource_is_url($path) { if (strpos($path, '://')) { // eg http:// https:// ftp:// etc return true; @@ -501,6 +640,11 @@ function resource_is_url($path) { return false; } +/** + * @global stdClass + * @uses MOD_CLASS_RESOURCE + * @return array + */ function resource_get_types() { global $CFG; @@ -535,14 +679,28 @@ function resource_get_types() { return $types; } +/** + * @return array + */ function resource_get_view_actions() { return array('view','view all'); } +/** + * @return array + */ function resource_get_post_actions() { return array(); } +/** + * @global stdClass + * @global object + * @param object $course + * @param string $wdir + * @param string $oldname + * @param string $name + */ function resource_renamefiles($course, $wdir, $oldname, $name) { global $CFG, $DB; @@ -592,6 +750,13 @@ function resource_renamefiles($course, $wdir, $oldname, $name) { } } +/** + * @global stdClass + * @global object + * @param object $course + * @param array $files + * @return bool + */ function resource_delete_warning($course, $files) { global $CFG, $DB; @@ -644,6 +809,7 @@ function resource_delete_warning($course, $files) { /** * This function is used by the reset_course_userdata function in moodlelib. + * * @param $data the data submitted from the reset course. * @return array status array */ @@ -653,22 +819,36 @@ function resource_reset_userdata($data) { /** * Returns all other caps used in module + * + * @return array */ function resource_get_extra_capabilities() { return array('moodle/site:accessallgroups'); } +/** + * @package mod-resource + * @copyright 1999 onwards Martin Dougiamas {@link http://moodle.com} + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ class resource_portfolio_caller extends portfolio_module_caller_base { private $resource; private $resourcefile; + /** + * @return array + */ public static function expected_callbackargs() { return array( 'id' => true, ); } + /** + * @global stdClass + * @global object + */ public function load_data() { global $CFG, $DB; if (!$this->cm = get_coursemodule_from_instance('resource', $this->id)) { @@ -686,6 +866,13 @@ class resource_portfolio_caller extends portfolio_module_caller_base { $this->supportedformats = array(self::type_to_format($this->cm->type)); } + /** + * @uses PORTFOLIO_FORMAT_FILE + * @uses PORTFOLIO_FORMAT_PLAINHTML + * @uses PORTFOLIO_FORMAT_TEXT + * @param string $type + * @return string + */ public static function type_to_format($type) { // this is kind of yuk... but there's just not good enough OO here $format = PORTFOLIO_FORMAT_FILE; @@ -700,6 +887,10 @@ class resource_portfolio_caller extends portfolio_module_caller_base { return $format; } + /** + * @global stdClass + * @return void + */ public function __wakeup() { global $CFG; if (empty($CFG)) { @@ -709,20 +900,38 @@ class resource_portfolio_caller extends portfolio_module_caller_base { $this->resource = unserialize(serialize($this->resource)); } + /** + * @todo penny check filesize if the type is uploadey (not implemented yet) + * like this: return portfolio_expected_time_file($this->file); or whatever + * + * @return string + */ public function expected_time() { - // @todo penny check filesize if the type is uploadey (not implemented yet) - // like this: return portfolio_expected_time_file($this->file); // or whatever return PORTFOLIO_TIME_LOW; } + /** + * + */ public function prepare_package() { return $this->resource->portfolio_prepare_package($this->exporter); } + /** + * @uses CONTEXT_MODULE + * @return bool + */ public function check_permissions() { return has_capability('mod/resource:exportresource', get_context_instance(CONTEXT_MODULE, $this->cm->id)); } + /** + * @uses CONTEXT_MODULE + * @param object $resource + * @param mixed $format + * @param bool $return + * @return mixed + */ public static function add_button($resource, $format=null, $return=false) { if (!has_capability('mod/resource:exportresource', get_context_instance(CONTEXT_MODULE, $resource->cm->id))) { return; @@ -744,18 +953,31 @@ class resource_portfolio_caller extends portfolio_module_caller_base { $button->render($format); } + /** + * @return string + */ public function get_sha1() { return $this->resource->portfolio_get_sha1(); } + /** + * @return string + */ public static function display_name() { return get_string('modulename', 'resource'); } } /** + * @uses FEATURE_GROUPS + * @uses FEATURE_GROUPINGS + * @uses FEATURE_GROUPMEMBERSONLY + * @uses FEATURE_MOD_INTRO + * @uses FEATURE_COMPLETION_TRACKS_VIEWS + * @uses FEATURE_GRADE_HAS_GRADE + * @uses FEATURE_GRADE_OUTCOMES * @param string $feature FEATURE_xx constant for requested feature - * @return mixed True if module supports feature, null if doesn't know + * @return mixed True if module supports feature, false if not, null if doesn't know */ function resource_supports($feature) { switch($feature) { @@ -777,6 +999,7 @@ function resource_supports($feature) { * level. * * @param string $type shortname (or directory name) of the resource type + * @return string */ function resource_get_name($type) { $name = get_string("resourcetype$type", "resource_$type"); diff --git a/mod/scorm/lib.php b/mod/scorm/lib.php index a9ca61027e..2b757875ef 100755 --- a/mod/scorm/lib.php +++ b/mod/scorm/lib.php @@ -1,22 +1,53 @@ -. +/** + * @package mod-scorm + * @copyright 1999 onwards Martin Dougiamas {@link http://moodle.com} + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ + +/** SCORM_TYPE_LOCAL = local */ define('SCORM_TYPE_LOCAL', 'local'); +/** SCORM_TYPE_LOCALSYNC = localsync */ define('SCORM_TYPE_LOCALSYNC', 'localsync'); +/** SCORM_TYPE_EXTERNAL = external */ define('SCORM_TYPE_EXTERNAL', 'external'); +/** SCORM_TYPE_IMSREPOSITORY = imsrepository */ define('SCORM_TYPE_IMSREPOSITORY', 'imsrepository'); /** -* Given an object containing all the necessary data, -* (defined by the form in mod_form.php) this function -* will create a new instance and return the id number -* of the new instance. -* -* @param object $scorm Form data -* @param object $mform -* @return int new instance id -*/ - + * Given an object containing all the necessary data, + * (defined by the form in mod_form.php) this function + * will create a new instance and return the id number + * of the new instance. + * + * @global stdClass + * @global object + * @uses CONTEXT_MODULE + * @uses SCORM_TYPE_LOCAL + * @uses SCORM_TYPE_LOCALSYNC + * @uses SCORM_TYPE_EXTERNAL + * @uses SCORM_TYPE_IMSREPOSITORY + * @param object $scorm Form data + * @param object $mform + * @return int new instance id + */ function scorm_add_instance($scorm, $mform=null) { global $CFG, $DB; @@ -96,14 +127,21 @@ function scorm_add_instance($scorm, $mform=null) { } /** -* Given an object containing all the necessary data, -* (defined by the form in mod_form.php) this function -* will update an existing instance with new data. -* -* @param object $scorm Form data -* @param object $mform -* @return bool success -*/ + * Given an object containing all the necessary data, + * (defined by the form in mod_form.php) this function + * will update an existing instance with new data. + * + * @global stdClass + * @global object + * @uses CONTEXT_MODULE + * @uses SCORM_TYPE_LOCAL + * @uses SCORM_TYPE_LOCALSYNC + * @uses SCORM_TYPE_EXTERNAL + * @uses SCORM_TYPE_IMSREPOSITORY + * @param object $scorm Form data + * @param object $mform + * @return bool + */ function scorm_update_instance($scorm, $mform=null) { global $CFG, $DB; @@ -175,13 +213,15 @@ function scorm_update_instance($scorm, $mform=null) { } /** -* Given an ID of an instance of this module, -* this function will permanently delete the instance -* and any data that depends on it. -* -* @param int $id Scorm instance id -* @return boolean -*/ + * Given an ID of an instance of this module, + * this function will permanently delete the instance + * and any data that depends on it. + * + * @global stdClass + * @global object + * @param int $id Scorm instance id + * @return boolean + */ function scorm_delete_instance($id) { global $CFG, $DB; @@ -237,16 +277,17 @@ function scorm_delete_instance($id) { } /** -* Return a small object with summary information about what a -* user has done with a given particular instance of this module -* Used for user activity reports. -* -* @param int $course Course id -* @param int $user User id -* @param int $mod -* @param int $scorm The scorm id -* @return mixed -*/ + * Return a small object with summary information about what a + * user has done with a given particular instance of this module + * Used for user activity reports. + * + * @global stdClass + * @param int $course Course id + * @param int $user User id + * @param int $mod + * @param int $scorm The scorm id + * @return mixed + */ function scorm_user_outline($course, $user, $mod, $scorm) { global $CFG; require_once('locallib.php'); @@ -257,15 +298,17 @@ function scorm_user_outline($course, $user, $mod, $scorm) { } /** -* Print a detailed representation of what a user has done with -* a given particular instance of this module, for user activity reports. -* -* @param int $course Course id -* @param int $user User id -* @param int $mod -* @param int $scorm The scorm id -* @return boolean -*/ + * Print a detailed representation of what a user has done with + * a given particular instance of this module, for user activity reports. + * + * @global stdClass + * @global object + * @param object $course + * @param object $user + * @param object $mod + * @param object $scorm + * @return boolean + */ function scorm_user_complete($course, $user, $mod, $scorm) { global $CFG, $DB; @@ -400,12 +443,14 @@ function scorm_user_complete($course, $user, $mod, $scorm) { } /** -* Function to be run periodically according to the moodle cron -* This function searches for things that need to be done, such -* as sending out mail, toggling flags etc ... -* -* @return boolean -*/ + * Function to be run periodically according to the moodle cron + * This function searches for things that need to be done, such + * as sending out mail, toggling flags etc ... + * + * @global stdClass + * @global object + * @return boolean + */ function scorm_cron () { global $CFG, $DB; @@ -439,6 +484,8 @@ function scorm_cron () { /** * Return grade for given user or all users. * + * @global stdClass + * @global object * @param int $scormid id of scorm * @param int $userid optional user id, 0 means all users * @return array array of grades, false if none @@ -476,8 +523,11 @@ function scorm_get_user_grades($scorm, $userid=0) { /** * Update grades in central gradebook * + * @global stdClass + * @global object * @param object $scorm * @param int $userid specific user only, 0 mean all + * @param bool $nullifnone */ function scorm_update_grades($scorm, $userid=0, $nullifnone=true) { global $CFG, $DB; @@ -499,6 +549,8 @@ function scorm_update_grades($scorm, $userid=0, $nullifnone=true) { /** * Update all grades in gradebook. + * + * @global object */ function scorm_upgrade_grades() { global $DB; @@ -527,8 +579,12 @@ function scorm_upgrade_grades() { /** * Update/create grade item for given scorm * + * @global stdClass + * @global object + * @uses GRADE_TYPE_VALUE + * @uses GRADE_TYPE_NONE * @param object $scorm object with extra cmidnumber - * @param mixed optional array/object of grade(s); 'reset' means reset grades in gradebook + * @param mixed $grades optional array/object of grade(s); 'reset' means reset grades in gradebook * @return object grade_item */ function scorm_grade_item_update($scorm, $grades=NULL) { @@ -567,6 +623,7 @@ function scorm_grade_item_update($scorm, $grades=NULL) { /** * Delete grade item for given scorm * + * @global stdClass * @param object $scorm object * @return object grade_item */ @@ -577,14 +634,24 @@ function scorm_grade_item_delete($scorm) { return grade_update('mod/scorm', $scorm->course, 'mod', 'scorm', $scorm->id, 0, NULL, array('deleted'=>1)); } +/** + * @return array + */ function scorm_get_view_actions() { return array('pre-view','view','view all','report'); } +/** + * @return array + */ function scorm_get_post_actions() { return array(); } +/** + * @param object $scorm + * @return object $scorm + */ function scorm_option2text($scorm) { $scorm_popoup_options = scorm_get_popup_options_array(); @@ -612,7 +679,8 @@ function scorm_option2text($scorm) { /** * Implementation of the function for printing the form elements that control * whether the course reset functionality affects the scorm. - * @param $mform form passed by reference + * + * @param object $mform form passed by reference */ function scorm_reset_course_form_definition(&$mform) { $mform->addElement('header', 'scormheader', get_string('modulenameplural', 'scorm')); @@ -621,6 +689,8 @@ function scorm_reset_course_form_definition(&$mform) { /** * Course reset form defaults. + * + * @return array */ function scorm_reset_course_form_defaults($course) { return array('reset_scorm'=>1); @@ -628,6 +698,9 @@ function scorm_reset_course_form_defaults($course) { /** * Removes all grades from gradebook + * + * @global stdClass + * @global object * @param int $courseid * @param string optional type */ @@ -648,7 +721,10 @@ function scorm_reset_gradebook($courseid, $type='') { /** * Actual implementation of the rest coures functionality, delete all the * scorm attempts for course $data->courseid. - * @param $data the data submitted from the reset course. + * + * @global stdClass + * @global object + * @param object $data the data submitted from the reset course. * @return array status array */ function scorm_reset_userdata($data) { @@ -679,6 +755,8 @@ function scorm_reset_userdata($data) { /** * Returns all other caps used in module + * + * @return array */ function scorm_get_extra_capabilities() { return array('moodle/site:accessallgroups'); @@ -686,6 +764,11 @@ function scorm_get_extra_capabilities() { /** * Lists all file areas current user may browse + * + * @param object $course + * @param object $cm + * @param object $context + * @return array */ function scorm_get_file_areas($course, $cm, $context) { $areas = array(); @@ -698,6 +781,8 @@ function scorm_get_file_areas($course, $cm, $context) { /** * File browsing support + * + * @todo Document this function */ function scorm_get_file_info($browser, $areas, $course, $cm, $context, $filearea, $itemid, $filepath, $filename) { global $CFG; @@ -724,6 +809,11 @@ function scorm_get_file_info($browser, $areas, $course, $cm, $context, $filearea return null; } } + /** + * @package mod-scorm + * @copyright 1999 onwards Martin Dougiamas {@link http://moodle.com} + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + */ class scorm_package_file_info extends file_info_stored { public function get_parent() { if ($this->lf->get_filepath() === '/' and $this->lf->get_filename() === '.') { @@ -763,6 +853,14 @@ function scorm_get_file_info($browser, $areas, $course, $cm, $context, $filearea /** * Serves scorm content, introduction images and packages. Implements needed access control ;-) + * + * @global stdClass + * @param object $course + * @param object $cminfo + * @param object $context + * @param string $filearea + * @param array $args + * @return bool */ function scorm_pluginfile($course, $cminfo, $context, $filearea, $args) { global $CFG; @@ -801,8 +899,15 @@ function scorm_pluginfile($course, $cminfo, $context, $filearea, $args) { } /** + * @uses FEATURE_GROUPS + * @uses FEATURE_GROUPINGS + * @uses FEATURE_GROUPMEMBERSONLY + * @uses FEATURE_MOD_INTRO + * @uses FEATURE_COMPLETION_TRACKS_VIEWS + * @uses FEATURE_GRADE_HAS_GRADE + * @uses FEATURE_GRADE_OUTCOMES * @param string $feature FEATURE_xx constant for requested feature - * @return mixed True if module supports feature, null if doesn't know + * @return mixed True if module supports feature, false if not, null if doesn't know */ function scorm_supports($feature) { switch($feature) { -- 2.39.5