MDL-30981 Upgrade API: Added related phpdocs
[moodle.git] / lib / db / upgrade.php
index 8d8ffff..8ead6e6 100644 (file)
@@ -1,5 +1,4 @@
 <?php
-
 // This file is part of Moodle - http://moodle.org/
 //
 // Moodle is free software: you can redistribute it and/or modify
  * Please do not forget to use upgrade_set_timeout()
  * before any action that may take longer time to finish.
  *
- * @package    core
- * @subpackage admin
- * @copyright  2006 onwards Martin Dougiamas  http://dougiamas.com
- * @license    http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @package   core_install
+ * @category  upgrade
+ * @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();
 
 /**
+ * Main upgrade tasks to be executed on Moodle version bump
+ *
+ * This function is automatically executed after one bump in the Moodle core
+ * version is detected. It's in charge of perform the required tasks
+ * to raise core from the previous version to the next one.
+ *
+ * It's a collection of ordered blocks of code, named "upgrade steps",
+ * each one performing one isolated (from the rest of steps) task. Usual
+ * tasks involve creating new DB objects or performing manipulation of the
+ * information for cleanup/fixup purposes.
+ *
+ * Each upgrade step has a fixed structure, that can be summarised as follows:
+ *
+ * if ($oldversion < XXXXXXXXXX.XX) {
+ *     // Explanation of the update step, linking to issue in the Tracker, if necessary
+ *     upgrade_set_timeout(XX); // Optional for big tasks
+ *     // Code to execute goes here, usually the XMLDB Editor will
+ *     // help you here. See {@link http://docs.moodle.org/dev/XMLDB_editor}.
+ *     upgrade_main_savepoint(true, XXXXXXXXXX.XX);
+ * }
+ *
+ * All plugins within Moodle (modules, blocks, reports...) support the existence of
+ * their own upgrade.php file, using the "Frankenstyle" component name as
+ * defined at {@link http://docs.moodle.org/dev/Frankenstyle}, for example:
+ *     - {@link xmldb_page_upgrade($oldversion)}. (modules don't require the plugintype ("mod_") to be used.
+ *     - {@link xmldb_auth_manual_upgrade($oldversion)}.
+ *     - {@link xmldb_workshopform_accumulative_upgrade($oldversion)}.
+ *     - ....
+ *
+ * In order to keep the contents of this file reduced, it's allowed to create some helper
+ * functions to be used here in the {@link upgradelib.php} file at the same directory. Note
+ * that such file must be manually included from upgrade.php, and there are some restrictions
+ * about what can be used within it.
+ *
+ * For more information, take a look to the documentation available:
+ *     - Data definition API: {@link http://docs.moodle.org/dev/Data_definition_API}
+ *     - Upgrade API: {@link http://docs.moodle.org/dev/Upgrade_API}
  *
- * @global stdClass $CFG
- * @global stdClass $USER
- * @global moodle_database $DB
- * @global core_renderer $OUTPUT
  * @param int $oldversion
  * @return bool always true
  */
@@ -67,9 +99,8 @@ function xmldb_main_upgrade($oldversion) {
         upgrade_main_savepoint(true, 2011120500);
     }
 
-    ////////////////////////////////////////
-    ///upgrade supported only from 2.2.x ///
-    ////////////////////////////////////////
+    // Moodle v2.2.0 release upgrade line
+    // Put any upgrade step following this
 
     if ($oldversion < 2011120500.02) {