From 39b90b5152eb63c23b640f452dc7dac63ec69dd6 Mon Sep 17 00:00:00 2001 From: "Eloy Lafuente (stronk7)" Date: Sun, 1 Apr 2012 22:48:17 +0200 Subject: [PATCH] MDL-30981 Upgrade API: Added related phpdocs --- lib/db/access.php | 12 ++++++--- lib/db/events.php | 14 +++++++--- lib/db/install.php | 63 ++++++++++++++++++++++++++++++------------- lib/db/log.php | 19 ++++++++----- lib/db/messages.php | 27 ++++++++++++------- lib/db/services.php | 9 +++++++ lib/db/upgrade.php | 55 ++++++++++++++++++++++++++++--------- lib/db/upgradelib.php | 9 +++---- lib/moodlelib.php | 3 ++- lib/upgradelib.php | 7 ++--- 10 files changed, 156 insertions(+), 62 deletions(-) diff --git a/lib/db/access.php b/lib/db/access.php index 8fe0b868ee5..76ebc668824 100644 --- a/lib/db/access.php +++ b/lib/db/access.php @@ -42,10 +42,14 @@ * * The variable name for the capability definitions array is $capabilities * - * @package core_access - * @category access - * @copyright 2006 onwards Martin Dougiamas http://dougiamas.com - * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * For more information, take a look to the documentation available: + * - Access API: {@link http://docs.moodle.org/dev/Access_API} + * - Upgrade API: {@link http://docs.moodle.org/dev/Upgrade_API} + * + * @package core_access + * @category access + * @copyright 2006 onwards Martin Dougiamas http://dougiamas.com + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ defined('MOODLE_INTERNAL') || die(); diff --git a/lib/db/events.php b/lib/db/events.php index 768691b22c2..51a8958c849 100644 --- a/lib/db/events.php +++ b/lib/db/events.php @@ -17,10 +17,18 @@ /** * Definition of core event handler and description of all events throws from core. * - * @package core - * @category event + * The handlers defined on this file are processed and registered into + * the Moodle DB after any install or upgrade operation. All plugins + * support this. + * + * For more information, take a look to the documentation available: + * - Events API: {@link http://docs.moodle.org/dev/Events_API} + * - Upgrade API: {@link http://docs.moodle.org/dev/Upgrade_API} + * + * @package core + * @category event * @copyright 2007 onwards Martin Dougiamas http://dougiamas.com - * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ defined('MOODLE_INTERNAL') || die(); diff --git a/lib/db/install.php b/lib/db/install.php index 8ad8f1a007b..f0bb45df6f9 100644 --- a/lib/db/install.php +++ b/lib/db/install.php @@ -1,5 +1,4 @@ id != SYSCONTEXTID) { throw new moodle_exception('generalexceptionmessage', 'error', '', 'Unexpected new system context id!'); } - /// Create site course + // Create site course if ($DB->record_exists('course', array())) { throw new moodle_exception('generalexceptionmessage', 'error', '', 'Can not create frontpage course, courses already exist.'); } @@ -69,7 +96,7 @@ function xmldb_main_install() { $SITE = $DB->get_record('course', array('id'=>$newsite->id), '*', MUST_EXIST); - /// Create default course category + // Create default course category if ($DB->record_exists('course_categories', array())) { throw new moodle_exception('generalexceptionmessage', 'error', '', 'Can not create default course category, categories already exist.'); } @@ -105,7 +132,7 @@ function xmldb_main_install() { } - /// Bootstrap mnet + // Bootstrap mnet $mnethost = new stdClass(); $mnethost->wwwroot = $CFG->wwwroot; $mnethost->name = ''; @@ -160,7 +187,7 @@ function xmldb_main_install() { $mnetallhosts->id = $DB->insert_record('mnet_host', $mnetallhosts, true); set_config('mnet_all_hosts_id', $mnetallhosts->id); - /// Create guest record - do not assign any role, guest user gets the default guest role automatically on the fly + // Create guest record - do not assign any role, guest user gets the default guest role automatically on the fly if ($DB->record_exists('user', array())) { throw new moodle_exception('generalexceptionmessage', 'error', '', 'Can not create default users, users already exist.'); } @@ -186,7 +213,7 @@ function xmldb_main_install() { context_user::instance($guest->id); - /// Now create admin user + // Now create admin user $admin = new stdClass(); $admin->auth = 'manual'; $admin->firstname = get_string('admin'); @@ -209,13 +236,13 @@ function xmldb_main_install() { echo $OUTPUT->notification('Nonconsecutive id generated for the Admin account. Your database configuration or clustering setup may not be fully supported.', 'notifyproblem'); } - /// Store list of admins + // Store list of admins set_config('siteadmins', $admin->id); // Make sure user context exists context_user::instance($admin->id); - /// Install the roles system. + // Install the roles system. $managerrole = create_role(get_string('manager', 'role'), 'manager', get_string('managerdescription', 'role'), 'manager'); $coursecreatorrole = create_role(get_string('coursecreators'), 'coursecreator', get_string('coursecreatorsdescription'), 'coursecreator'); $editteacherrole = create_role(get_string('defaultcourseteacher'), 'editingteacher', get_string('defaultcourseteacherdescription'), 'editingteacher'); @@ -225,10 +252,10 @@ function xmldb_main_install() { $userrole = create_role(get_string('authenticateduser'), 'user', get_string('authenticateduserdescription'), 'user'); $frontpagerole = create_role(get_string('frontpageuser', 'role'), 'frontpage', get_string('frontpageuserdescription', 'role'), 'frontpage'); - /// Now is the correct moment to install capabilities - after creation of legacy roles, but before assigning of roles + // Now is the correct moment to install capabilities - after creation of legacy roles, but before assigning of roles update_capabilities('moodle'); - /// Default allow assign + // Default allow assign $defaultallowassigns = array( array($managerrole, $managerrole), array($managerrole, $coursecreatorrole), @@ -244,7 +271,7 @@ function xmldb_main_install() { allow_assign($fromroleid, $toroleid); } - /// Default allow override + // Default allow override $defaultallowoverrides = array( array($managerrole, $managerrole), array($managerrole, $coursecreatorrole), @@ -264,7 +291,7 @@ function xmldb_main_install() { allow_override($fromroleid, $toroleid); // There is a rant about this in MDL-15841. } - /// Default allow switch. + // Default allow switch. $defaultallowswitch = array( array($managerrole, $editteacherrole), array($managerrole, $noneditteacherrole), @@ -283,7 +310,7 @@ function xmldb_main_install() { allow_switch($fromroleid, $toroleid); } - /// Set up the context levels where you can assign each role. + // Set up the context levels where you can assign each role. set_role_contextlevels($managerrole, get_default_contextlevels('manager')); set_role_contextlevels($coursecreatorrole, get_default_contextlevels('coursecreator')); set_role_contextlevels($editteacherrole, get_default_contextlevels('editingteacher')); diff --git a/lib/db/log.php b/lib/db/log.php index 7549e34ec22..f404e019e0c 100644 --- a/lib/db/log.php +++ b/lib/db/log.php @@ -1,5 +1,4 @@ . /** - * Definition of log events + * Definition of log events associated with the current component + * + * The log events defined on this file are processed and stored into + * the Moodle DB after any install or upgrade operation. All plugins + * support this. + * + * For more information, take a look to the documentation available: + * - Logging API: {@link http://docs.moodle.org/dev/Logging_API} + * - Upgrade API: {@link http://docs.moodle.org/dev/Upgrade_API} * - * @package core - * @subpackage admin - * @copyright 2010 Petr Skoda (http://skodak.org) - * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later + * @package core + * @category log + * @copyright 2010 Petr Skoda (http://skodak.org) + * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later */ defined('MOODLE_INTERNAL') || die(); diff --git a/lib/db/messages.php b/lib/db/messages.php index db087fb5f3d..30bc820cc8d 100644 --- a/lib/db/messages.php +++ b/lib/db/messages.php @@ -1,5 +1,4 @@ array ( 'capability' => 'moodle/site:config' ), -/// Important errors that an admin ought to know about + // Important errors that an admin ought to know about 'errors' => array ( 'capability' => 'moodle/site:config' ), @@ -49,17 +56,17 @@ $messageproviders = array ( 'capability' => 'moodle/site:config' ), - //course creation request notification + // Course creation request notification 'courserequested' => array ( 'capability' => 'moodle/site:approvecourse' ), - //course request approval notification + // Course request approval notification 'courserequestapproved' => array ( 'capability' => 'moodle/course:request' ), - //course request rejection notification + // Course request rejection notification 'courserequestrejected' => array ( 'capability' => 'moodle/course:request' ) diff --git a/lib/db/services.php b/lib/db/services.php index 328d29db578..cdb6a5741c3 100644 --- a/lib/db/services.php +++ b/lib/db/services.php @@ -18,6 +18,15 @@ /** * Core external functions and service definitions. * + * The functions and services defined on this file are + * processed and registered into the Moodle DB after any + * install or upgrade operation. All plugins support this. + * + * For more information, take a look to the documentation available: + * - Webservices API: {@link http://docs.moodle.org/dev/Web_services_API} + * - External API: {@link http://docs.moodle.org/dev/External_functions_API} + * - Upgrade API: {@link http://docs.moodle.org/dev/Upgrade_API} + * * @package core_webservice * @category webservice * @copyright 2009 Petr Skodak diff --git a/lib/db/upgrade.php b/lib/db/upgrade.php index 8d8fffff515..8ead6e6cb3d 100644 --- a/lib/db/upgrade.php +++ b/lib/db/upgrade.php @@ -1,5 +1,4 @@