From c0f384fa57da07d74319570fdb213fba9a8c81d8 Mon Sep 17 00:00:00 2001
From: Jennifer Hodgdon <yahgrp@poplarware.com>
Date: Wed, 6 Jun 2012 08:33:53 -0700
Subject: [PATCH] Issue #1431634 by Tor Arne Thune: API docs cleanup for update
module
---
.../Drupal/update/Tests/UpdateContribTest.php | 36 +--
.../Drupal/update/Tests/UpdateCoreTest.php | 26 ++-
.../update/Tests/UpdateCoreUnitTest.php | 5 +-
.../Drupal/update/Tests/UpdateTestBase.php | 41 ++--
.../Drupal/update/Tests/UpdateUploadTest.php | 10 +-
.../modules/update_test/update_test.module | 69 ++++--
core/modules/update/update-rtl.css | 4 +
core/modules/update/update.api.php | 30 +--
core/modules/update/update.authorize.inc | 83 ++++---
core/modules/update/update.compare.inc | 189 +++++++++-------
core/modules/update/update.css | 4 +
core/modules/update/update.fetch.inc | 54 +++--
core/modules/update/update.install | 37 ++--
core/modules/update/update.manager.inc | 185 +++++++++-------
core/modules/update/update.module | 207 ++++++++++--------
core/modules/update/update.report.inc | 5 +-
core/modules/update/update.settings.inc | 26 ++-
17 files changed, 593 insertions(+), 418 deletions(-)
diff --git a/core/modules/update/lib/Drupal/update/Tests/UpdateContribTest.php b/core/modules/update/lib/Drupal/update/Tests/UpdateContribTest.php
index 91141cd478f7..73df9a137259 100644
--- a/core/modules/update/lib/Drupal/update/Tests/UpdateContribTest.php
+++ b/core/modules/update/lib/Drupal/update/Tests/UpdateContribTest.php
@@ -7,12 +7,15 @@
namespace Drupal\update\Tests;
+/**
+ * Tests behavior related to handling updates to contributed modules and themes.
+ */
class UpdateContribTest extends UpdateTestBase {
public static function getInfo() {
return array(
'name' => 'Update contrib functionality',
- 'description' => 'Tests how the update module handles contributed modules and themes in a series of functional tests using mock XML data.',
+ 'description' => 'Tests how the Update Manager module handles contributed modules and themes in a series of functional tests using mock XML data.',
'group' => 'Update',
);
}
@@ -52,7 +55,7 @@ function testNoReleasesAvailable() {
}
/**
- * Test the basic functionality of a contrib module on the status report.
+ * Tests the basic functionality of a contrib module on the status report.
*/
function testUpdateContribBasic() {
$system_info = array(
@@ -80,17 +83,17 @@ function testUpdateContribBasic() {
}
/**
- * Test that contrib projects are ordered by project name.
+ * Tests that contrib projects are ordered by project name.
*
* If a project contains multiple modules, we want to make sure that the
- * available updates report is sorted by the parent project names, not by
- * the names of the modules included in each project. In this test case, we
- * have 2 contrib projects, "BBB Update test" and "CCC Update test".
- * However, we have a module called "aaa_update_test" that's part of the
- * "CCC Update test" project. We need to make sure that we see the "BBB"
- * project before the "CCC" project, even though "CCC" includes a module
- * that's processed first if you sort alphabetically by module name (which
- * is the order we see things inside system_rebuild_module_data() for example).
+ * available updates report is sorted by the parent project names, not by the
+ * names of the modules included in each project. In this test case, we have
+ * two contrib projects, "BBB Update test" and "CCC Update test". However, we
+ * have a module called "aaa_update_test" that's part of the "CCC Update test"
+ * project. We need to make sure that we see the "BBB" project before the
+ * "CCC" project, even though "CCC" includes a module that's processed first
+ * if you sort alphabetically by module name (which is the order we see things
+ * inside system_rebuild_module_data() for example).
*/
function testUpdateContribOrder() {
// We want core to be version 7.0.
@@ -152,7 +155,7 @@ function testUpdateContribOrder() {
}
/**
- * Test that subthemes are notified about security updates for base themes.
+ * Tests that subthemes are notified about security updates for base themes.
*/
function testUpdateBaseThemeSecurityUpdate() {
// Only enable the subtheme, not the base theme.
@@ -193,7 +196,7 @@ function testUpdateBaseThemeSecurityUpdate() {
}
/**
- * Test that disabled themes are only shown when desired.
+ * Tests that disabled themes are only shown when desired.
*/
function testUpdateShowDisabledThemes() {
// Make sure all the update_test_* themes are disabled.
@@ -254,7 +257,7 @@ function testUpdateShowDisabledThemes() {
}
/**
- * Make sure that if we fetch from a broken URL, sane things happen.
+ * Makes sure that if we fetch from a broken URL, sane things happen.
*/
function testUpdateBrokenFetchURL() {
$system_info = array(
@@ -310,13 +313,12 @@ function testUpdateBrokenFetchURL() {
}
/**
- * Check that hook_update_status_alter() works to change a status.
+ * Checks that hook_update_status_alter() works to change a status.
*
* We provide the same external data as if aaa_update_test 8.x-1.0 were
* installed and that was the latest release. Then we use
* hook_update_status_alter() to try to mark this as missing a security
- * update, then assert if we see the appropriate warnings on the right
- * pages.
+ * update, then assert if we see the appropriate warnings on the right pages.
*/
function testHookUpdateStatusAlter() {
variable_set('allow_authorize_operations', TRUE);
diff --git a/core/modules/update/lib/Drupal/update/Tests/UpdateCoreTest.php b/core/modules/update/lib/Drupal/update/Tests/UpdateCoreTest.php
index f4b9989dbc94..0679f88ae16f 100644
--- a/core/modules/update/lib/Drupal/update/Tests/UpdateCoreTest.php
+++ b/core/modules/update/lib/Drupal/update/Tests/UpdateCoreTest.php
@@ -7,12 +7,15 @@
namespace Drupal\update\Tests;
+/**
+ * Tests behavior related to discovering and listing updates to Drupal core.
+ */
class UpdateCoreTest extends UpdateTestBase {
public static function getInfo() {
return array(
'name' => 'Update core functionality',
- 'description' => 'Tests the update module through a series of functional tests using mock XML data.',
+ 'description' => 'Tests the Update Manager module through a series of functional tests using mock XML data.',
'group' => 'Update',
);
}
@@ -24,7 +27,7 @@ function setUp() {
}
/**
- * Tests the update module when no updates are available.
+ * Tests the Update Manager module when no updates are available.
*/
function testNoUpdatesAvailable() {
$this->setSystemInfo7_0();
@@ -36,7 +39,7 @@ function testNoUpdatesAvailable() {
}
/**
- * Tests the update module when one normal update ("7.1") is available.
+ * Tests the Update Manager module when one normal update is available.
*/
function testNormalUpdateAvailable() {
$this->setSystemInfo7_0();
@@ -51,7 +54,7 @@ function testNormalUpdateAvailable() {
}
/**
- * Tests the update module when a security update ("7.2") is available.
+ * Tests the Update Manager module when a security update is available.
*/
function testSecurityUpdateAvailable() {
$this->setSystemInfo7_0();
@@ -66,7 +69,7 @@ function testSecurityUpdateAvailable() {
}
/**
- * Ensure proper results where there are date mismatches among modules.
+ * Ensures proper results where there are date mismatches among modules.
*/
function testDatestampMismatch() {
$system_info = array(
@@ -89,7 +92,7 @@ function testDatestampMismatch() {
}
/**
- * Check that running cron updates the list of available updates.
+ * Checks that running cron updates the list of available updates.
*/
function testModulePageRunCron() {
$this->setSystemInfo7_0();
@@ -102,7 +105,7 @@ function testModulePageRunCron() {
}
/**
- * Check the messages at admin/modules when the site is up to date.
+ * Checks the messages at admin/modules when the site is up to date.
*/
function testModulePageUpToDate() {
$this->setSystemInfo7_0();
@@ -119,7 +122,7 @@ function testModulePageUpToDate() {
}
/**
- * Check the messages at admin/modules when missing an update.
+ * Checks the messages at admin/modules when an update is missing.
*/
function testModulePageRegularUpdate() {
$this->setSystemInfo7_0();
@@ -136,7 +139,7 @@ function testModulePageRegularUpdate() {
}
/**
- * Check the messages at admin/modules when missing a security update.
+ * Checks the messages at admin/modules when a security update is missing.
*/
function testModulePageSecurityUpdate() {
$this->setSystemInfo7_0();
@@ -171,7 +174,7 @@ function testModulePageSecurityUpdate() {
}
/**
- * Tests the update module when the update server returns 503 (Service unavailable) errors.
+ * Tests the Update Manager module when the update server returns 503 errors.
*/
function testServiceUnavailable() {
$this->refreshUpdateStatus(array(), '503-error');
@@ -207,6 +210,9 @@ function testFetchTasks() {
$this->assertEqual($queue->numberOfItems(), 2, 'Queue contains two items');
}
+ /**
+ * Sets the version to 7.0 when no project-specific mapping is defined.
+ */
protected function setSystemInfo7_0() {
$setting = array(
'#all' => array(
diff --git a/core/modules/update/lib/Drupal/update/Tests/UpdateCoreUnitTest.php b/core/modules/update/lib/Drupal/update/Tests/UpdateCoreUnitTest.php
index 464852651463..2a33818846f6 100644
--- a/core/modules/update/lib/Drupal/update/Tests/UpdateCoreUnitTest.php
+++ b/core/modules/update/lib/Drupal/update/Tests/UpdateCoreUnitTest.php
@@ -9,6 +9,9 @@
use Drupal\simpletest\UnitTestBase;
+/**
+ * Tests update functionality unrelated to the database.
+ */
class UpdateCoreUnitTest extends UnitTestBase {
public static function getInfo() {
@@ -25,7 +28,7 @@ function setUp() {
}
/**
- * Tests _update_build_fetch_url according to issue 1481156
+ * Tests that _update_build_fetch_url() builds the URL correctly.
*/
function testUpdateBuildFetchUrl() {
//first test that we didn't break the trivial case
diff --git a/core/modules/update/lib/Drupal/update/Tests/UpdateTestBase.php b/core/modules/update/lib/Drupal/update/Tests/UpdateTestBase.php
index 7399d3c52acd..fe603e268f9a 100644
--- a/core/modules/update/lib/Drupal/update/Tests/UpdateTestBase.php
+++ b/core/modules/update/lib/Drupal/update/Tests/UpdateTestBase.php
@@ -4,18 +4,18 @@
* @file
* Definition of Drupal\update\Tests\UpdateTestBase.
*
- * This file contains tests for the update module. The overarching methodology
- * of these tests is we need to compare a given state of installed modules and
- * themes (e.g. version, project grouping, timestamps, etc) vs. a current
- * state of what the release history XML files we fetch say is available. We
- * have dummy XML files (in the 'tests' subdirectory) that describe various
- * scenarios of what's available for different test projects, and we have
- * dummy .info file data (specified via hook_system_info_alter() in the
- * update_test helper module) describing what's currently installed. Each
- * test case defines a set of projects to install, their current state (via
- * the 'update_test_system_info' variable) and the desired available update
- * data (via the 'update_test_xml_map' variable), and then performs a series
- * of assertions that the report matches our expectations given the specific
+ * The overarching methodology of these tests is we need to compare a given
+ * state of installed modules and themes (e.g., version, project grouping,
+ * timestamps, etc) against a current state of what the release history XML
+ * files we fetch say is available. We have dummy XML files (in the
+ * core/modules/update/tests directory) that describe various scenarios of
+ * what's available for different test projects, and we have dummy .info file
+ * data (specified via hook_system_info_alter() in the update_test helper
+ * module) describing what's currently installed. Each test case defines a set
+ * of projects to install, their current state (via the
+ * 'update_test_system_info' variable) and the desired available update data
+ * (via the 'update_test_xml_map' variable), and then performs a series of
+ * assertions that the report matches our expectations given the specific
* initial state and availability scenario.
*/
@@ -24,20 +24,25 @@
use Drupal\simpletest\WebTestBase;
/**
- * Base class to define some shared functions used by all update tests.
+ * Defines some shared functions used by all update tests.
*/
class UpdateTestBase extends WebTestBase {
+
/**
- * Refresh the update status based on the desired available update scenario.
+ * Refreshes the update status based on the desired available update scenario.
*
* @param $xml_map
- * Array that maps project names to availability scenarios to fetch.
- * The key '#all' is used if a project-specific mapping is not defined.
+ * Array that maps project names to availability scenarios to fetch. The key
+ * '#all' is used if a project-specific mapping is not defined.
+ * @param $url
+ * (optional) A string containing the URL to fetch update data from.
+ * Defaults to 'update-test'.
*
* @see update_test_mock_page()
*/
protected function refreshUpdateStatus($xml_map, $url = 'update-test') {
- // Tell update module to fetch from the URL provided by update_test module.
+ // Tell the Update Manager module to fetch from the URL provided by
+ // update_test module.
variable_set('update_fetch_url', url($url, array('absolute' => TRUE)));
// Save the map for update_test_mock_page() to use.
variable_set('update_test_xml_map', $xml_map);
@@ -46,7 +51,7 @@ protected function refreshUpdateStatus($xml_map, $url = 'update-test') {
}
/**
- * Run a series of assertions that are applicable for all update statuses.
+ * Runs a series of assertions that are applicable to all update statuses.
*/
protected function standardTests() {
$this->assertRaw('<h3>' . t('Drupal core') . '</h3>');
diff --git a/core/modules/update/lib/Drupal/update/Tests/UpdateUploadTest.php b/core/modules/update/lib/Drupal/update/Tests/UpdateUploadTest.php
index fae57db0b80e..4475888584df 100644
--- a/core/modules/update/lib/Drupal/update/Tests/UpdateUploadTest.php
+++ b/core/modules/update/lib/Drupal/update/Tests/UpdateUploadTest.php
@@ -7,11 +7,15 @@
namespace Drupal\update\Tests;
+/**
+ * Tests project upload and extract functionality.
+ */
class UpdateUploadTest extends UpdateTestBase {
+
public static function getInfo() {
return array(
'name' => 'Upload and extract module functionality',
- 'description' => 'Tests the update module\'s upload and extraction functionality.',
+ 'description' => 'Tests the Update Manager module\'s upload and extraction functionality.',
'group' => 'Update',
);
}
@@ -52,7 +56,7 @@ public function testUploadModule() {
}
/**
- * Ensure that archiver extensions are properly merged in the UI.
+ * Ensures that archiver extensions are properly merged in the UI.
*/
function testFileNameExtensionMerging() {
$this->drupalGet('admin/modules/install');
@@ -63,7 +67,7 @@ function testFileNameExtensionMerging() {
}
/**
- * Check the messages on Update manager pages when missing a security update.
+ * Checks the messages on update manager pages when missing a security update.
*/
function testUpdateManagerCoreSecurityUpdateMessages() {
$setting = array(
diff --git a/core/modules/update/tests/modules/update_test/update_test.module b/core/modules/update/tests/modules/update_test/update_test.module
index 6254d251e7db..30a414193d78 100644
--- a/core/modules/update/tests/modules/update_test/update_test.module
+++ b/core/modules/update/tests/modules/update_test/update_test.module
@@ -3,6 +3,11 @@
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpFoundation\StreamedResponse;
+/**
+ * @file
+ * Module for testing Update Manager functionality.
+ */
+
/**
* Implements hook_system_theme_info().
*/
@@ -37,13 +42,13 @@ function update_test_menu() {
/**
* Implements hook_system_info_alter().
*
- * This checks the 'update_test_system_info' variable and sees if we need to
- * alter the system info for the given $file based on the setting. The setting
- * is expected to be a nested associative array. If the key '#all' is defined,
- * its subarray will include .info keys and values for all modules and themes
- * on the system. Otherwise, the settings array is keyed by the module or
- * theme short name ($file->name) and the subarrays contain settings just for
- * that module or theme.
+ * Checks the 'update_test_system_info' variable and sees if we need to alter
+ * the system info for the given $file based on the setting. The setting is
+ * expected to be a nested associative array. If the key '#all' is defined, its
+ * subarray will include .info keys and values for all modules and themes on the
+ * system. Otherwise, the settings array is keyed by the module or theme short
+ * name ($file->name) and the subarrays contain settings just for that module or
+ * theme.
*/
function update_test_system_info_alter(&$info, $file) {
$setting = variable_get('update_test_system_info', array());
@@ -59,13 +64,12 @@ function update_test_system_info_alter(&$info, $file) {
/**
* Implements hook_update_status_alter().
*
- * This checks the 'update_test_update_status' variable and sees if we need to
- * alter the update status for the given project based on the setting. The
- * setting is expected to be a nested associative array. If the key '#all' is
- * defined, its subarray will include .info keys and values for all modules
- * and themes on the system. Otherwise, the settings array is keyed by the
- * module or theme short name and the subarrays contain settings just for that
- * module or theme.
+ * Checks the 'update_test_update_status' variable and sees if we need to alter
+ * the update status for the given project based on the setting. The setting is
+ * expected to be a nested associative array. If the key '#all' is defined, its
+ * subarray will include .info keys and values for all modules and themes on the
+ * system. Otherwise, the settings array is keyed by the module or theme short
+ * name and the subarrays contain settings just for that module or theme.
*/
function update_test_update_status_alter(&$projects) {
$setting = variable_get('update_test_update_status', array());
@@ -83,18 +87,25 @@ function update_test_update_status_alter(&$projects) {
}
/**
- * Page callback, prints mock XML for the update module.
+ * Page callback: Prints mock XML for the Update Manager module.
*
* The specific XML file to print depends on two things: the project we're
* trying to fetch data for, and the desired "availability scenario" for that
- * project which we're trying to test. Before attempting to fetch this data
- * (by checking for updates on the available updates report), callers need to
- * define the 'update_test_xml_map' variable as an array, keyed by project
- * name, indicating which availability scenario to use for that project.
+ * project which we're trying to test. Before attempting to fetch this data (by
+ * checking for updates on the available updates report), callers need to define
+ * the 'update_test_xml_map' variable as an array, keyed by project name,
+ * indicating which availability scenario to use for that project.
*
* @param $project_name
- * The project short name update.module is trying to fetch data for (the
+ * The project short name the update manager is trying to fetch data for (the
* fetch URLs are of the form: [base_url]/[project_name]/[core_version]).
+ *
+ * @return StreamedResponse|Response
+ * A StreamedResponse object containing the content of the XML release file
+ * for the specified project if one is available; a Response object with no
+ * content otherwise.
+ *
+ * @see update_test_menu()
*/
function update_test_mock_page($project_name) {
$xml_map = variable_get('update_test_xml_map', FALSE);
@@ -124,7 +135,7 @@ function update_test_mock_page($project_name) {
}
/**
- * Implement hook_archiver_info().
+ * Implements hook_archiver_info().
*/
function update_test_archiver_info() {
return array(
@@ -156,13 +167,23 @@ function update_test_filetransfer_info() {
}
/**
- * Mock FileTransfer object to test the settings form functionality.
+ * Mocks a FileTransfer object to test the settings form functionality.
*/
class UpdateTestFileTransfer {
+
+ /**
+ * Returns an UpdateTestFileTransfer object.
+ *
+ * @return
+ * A new UpdateTestFileTransfer object.
+ */
public static function factory() {
return new UpdateTestFileTransfer;
}
+ /**
+ * Returns a settings form with a text field to input a username.
+ */
public function getSettingsForm() {
$form = array();
$form['udpate_test_username'] = array(
@@ -174,7 +195,9 @@ public function getSettingsForm() {
}
/**
- * Return an Error 503 (Service unavailable) page.
+ * Page callback: Displays an Error 503 (Service unavailable) page.
+ *
+ * @see update_test_menu()
*/
function update_callback_service_unavailable() {
drupal_add_http_header('Status', '503 Service unavailable');
diff --git a/core/modules/update/update-rtl.css b/core/modules/update/update-rtl.css
index 5fc83d1a6239..f181c845465f 100644
--- a/core/modules/update/update-rtl.css
+++ b/core/modules/update/update-rtl.css
@@ -1,3 +1,7 @@
+/**
+ * @file
+ * RTL styles used by the Update Manager module.
+ */
.update .project {
padding-right: .25em;
diff --git a/core/modules/update/update.api.php b/core/modules/update/update.api.php
index 5f68f0ed2948..6233e4028795 100644
--- a/core/modules/update/update.api.php
+++ b/core/modules/update/update.api.php
@@ -2,7 +2,7 @@
/**
* @file
- * Hooks provided by the Update Status module.
+ * Hooks provided by the Update Manager module.
*/
/**
@@ -14,23 +14,22 @@
* Alter the list of projects before fetching data and comparing versions.
*
* Most modules will never need to implement this hook. It is for advanced
- * interaction with the update status module: mere mortals need not apply.
- * The primary use-case for this hook is to add projects to the list, for
- * example, to provide update status data on disabled modules and themes. A
- * contributed module might want to hide projects from the list, for example,
- * if there is a site-specific module that doesn't have any official releases,
- * that module could remove itself from this list to avoid "No available
- * releases found" warnings on the available updates report. In rare cases, a
- * module might want to alter the data associated with a project already in
- * the list.
+ * interaction with the Update Manager module. The primary use-case for this
+ * hook is to add projects to the list; for example, to provide update status
+ * data on disabled modules and themes. A contributed module might want to hide
+ * projects from the list; for example, if there is a site-specific module that
+ * doesn't have any official releases, that module could remove itself from this
+ * list to avoid "No available releases found" warnings on the available updates
+ * report. In rare cases, a module might want to alter the data associated with
+ * a project already in the list.
*
* @param $projects
* Reference to an array of the projects installed on the system. This
- * includes all the metadata documented in the comments below for each
- * project (either module or theme) that is currently enabled. The array is
- * initially populated inside update_get_projects() with the help of
- * update_process_info_list(), so look there for examples of how to
- * populate the array with real values.
+ * includes all the metadata documented in the comments below for each project
+ * (either module or theme) that is currently enabled. The array is initially
+ * populated inside update_get_projects() with the help of
+ * update_process_info_list(), so look there for examples of how to populate
+ * the array with real values.
*
* @see update_get_projects()
* @see update_process_info_list()
@@ -118,6 +117,7 @@ function hook_update_status_alter(&$projects) {
* no problems, return an empty array.
*
* @see update_manager_archive_verify()
+ * @ingroup update_manager_file
*/
function hook_verify_update_archive($project, $archive_file, $directory) {
$errors = array();
diff --git a/core/modules/update/update.authorize.inc b/core/modules/update/update.authorize.inc
index 48dfd353f219..37195e13bd65 100644
--- a/core/modules/update/update.authorize.inc
+++ b/core/modules/update/update.authorize.inc
@@ -2,17 +2,21 @@
/**
* @file
- * Callbacks and related functions invoked by authorize.php to update projects
- * on the Drupal site. We use the Batch API to actually update each individual
- * project on the site. All of the code in this file is run at a low bootstrap
- * level (modules are not loaded), so these functions cannot assume access to
- * the rest of the update module code.
+ * Callbacks and related functions invoked by authorize.php to update projects.
+ *
+ * We use the Batch API to actually update each individual project on the site.
+ * All of the code in this file is run at a low bootstrap level (modules are not
+ * loaded), so these functions cannot assume access to the rest of the code of
+ * the Update Manager module.
*/
use Drupal\Core\Updater\UpdaterException;
/**
- * Callback invoked by authorize.php to update existing projects.
+ * Updates existing projects when invoked by authorize.php.
+ *
+ * Callback for system_authorized_init() in
+ * update_manager_update_ready_form_submit().
*
* @param $filetransfer
* The FileTransfer object created by authorize.php for use during this
@@ -20,10 +24,10 @@
* @param $projects
* A nested array of projects to install into the live webroot, keyed by
* project name. Each subarray contains the following keys:
- * - 'project': The canonical project short name.
- * - 'updater_name': The name of the Drupal\Core\Updater\Updater class to use
+ * - project: The canonical project short name.
+ * - updater_name: The name of the Drupal\Core\Updater\Updater class to use
* for this project.
- * - 'local_url': The locally installed location of new code to update with.
+ * - local_url: The locally installed location of new code to update with.
*/
function update_authorize_run_update($filetransfer, $projects) {
$operations = array();
@@ -53,13 +57,16 @@ function update_authorize_run_update($filetransfer, $projects) {
}
/**
- * Callback invoked by authorize.php to install a new project.
+ * Installs a new project when invoked by authorize.php.
+ *
+ * Callback for system_authorized_init() in
+ * update_manager_install_form_submit().
*
* @param FileTransfer $filetransfer
* The FileTransfer object created by authorize.php for use during this
* operation.
* @param string $project
- * The canonical project short name (e.g. {system}.name).
+ * The canonical project short name (e.g., {system}.name).
* @param string $updater_name
* The name of the Drupal\Core\Updater\Updater class to use for installing
* this project.
@@ -94,7 +101,7 @@ function update_authorize_run_install($filetransfer, $project, $updater_name, $l
}
/**
- * Copy a project to its proper place when authorized with elevated privileges.
+ * Batch callback: Copies project to its proper place when authorized to do so.
*
* @param string $project
* The canonical short name of the project being installed.
@@ -107,7 +114,7 @@ function update_authorize_run_install($filetransfer, $project, $updater_name, $l
* @param FileTransfer $filetransfer
* The FileTransfer object to use for performing this operation.
* @param array $context
- * Reference to an array used for BatchAPI storage.
+ * Reference to an array used for Batch API storage.
*/
function update_authorize_batch_copy_project($project, $updater_name, $local_url, $filetransfer, &$context) {
@@ -123,15 +130,13 @@ function update_authorize_batch_copy_project($project, $updater_name, $local_url
$context['results']['tasks'] = array();
}
- /**
- * The batch API uses a session, and since all the arguments are serialized
- * and unserialized between requests, although the FileTransfer object
- * itself will be reconstructed, the connection pointer itself will be lost.
- * However, the FileTransfer object will still have the connection variable,
- * even though the connection itself is now gone. So, although it's ugly, we
- * have to unset the connection variable at this point so that the
- * FileTransfer object will re-initiate the actual connection.
- */
+ // The batch API uses a session, and since all the arguments are serialized
+ // and unserialized between requests, although the FileTransfer object itself
+ // will be reconstructed, the connection pointer itself will be lost. However,
+ // the FileTransfer object will still have the connection variable, even
+ // though the connection itself is now gone. So, although it's ugly, we have
+ // to unset the connection variable at this point so that the FileTransfer
+ // object will re-initiate the actual connection.
unset($filetransfer->connection);
if (!empty($context['results']['log'][$project]['#abort'])) {
@@ -168,11 +173,16 @@ function update_authorize_batch_copy_project($project, $updater_name, $local_url
}
/**
- * Batch callback for when the authorized update batch is finished.
+ * Batch callback: Performs actions when the authorized update batch is done.
*
* This processes the results and stashes them into SESSION such that
* authorize.php will render a report. Also responsible for putting the site
* back online and clearing the update status cache after a successful update.
+ *
+ * @param $success
+ * TRUE if the batch operation was successful; FALSE if there were errors.
+ * @param $results
+ * An associative array of results from the batch operation.
*/
function update_authorize_update_batch_finished($success, $results) {
foreach ($results['log'] as $project => $messages) {
@@ -230,11 +240,16 @@ function update_authorize_update_batch_finished($success, $results) {
}
/**
- * Batch callback for when the authorized install batch is finished.
+ * Batch callback: Performs actions when the authorized install batch is done.
*
* This processes the results and stashes them into SESSION such that
* authorize.php will render a report. Also responsible for putting the site
* back online after a successful install if necessary.
+ *
+ * @param $success
+ * TRUE if the batch operation was a success; FALSE if there were errors.
+ * @param $results
+ * An associative array of results from the batch operation.
*/
function update_authorize_install_batch_finished($success, $results) {
foreach ($results['log'] as $project => $messages) {
@@ -284,26 +299,30 @@ function update_authorize_install_batch_finished($success, $results) {
}
/**
- * Helper function to create a structure of log messages.
+ * Creates a structure of log messages.
*
* @param array $project_results
+ * An associative array of results from the batch operation.
* @param string $message
+ * A string containing a log message.
* @param bool $success
+ * (optional) TRUE if the operation the message is about was a success, FALSE
+ * if there were errors. Defaults to TRUE.
*/
function _update_batch_create_message(&$project_results, $message, $success = TRUE) {
$project_results[] = array('message' => $message, 'success' => $success);
}
/**
- * Private helper function to clear cached available update status data.
+ * Clears cached available update status data.
*
- * Since this function is run at such a low bootstrap level, update.module is
- * not loaded. So, we can't just call _update_cache_clear(). However, the
- * database is bootstrapped, so we can do a query ourselves to clear out what
- * we want to clear.
+ * Since this function is run at such a low bootstrap level, the Update Manager
+ * module is not loaded. So, we can't just call _update_cache_clear(). However,
+ * the database is bootstrapped, so we can do a query ourselves to clear out
+ * what we want to clear.
*
- * Note that we do not want to just truncate the table, since that would
- * remove items related to currently pending fetch attempts.
+ * Note that we do not want to just truncate the table, since that would remove
+ * items related to currently pending fetch attempts.
*
* @see update_authorize_update_batch_finished()
* @see _update_cache_clear()
diff --git a/core/modules/update/update.compare.inc b/core/modules/update/update.compare.inc
index 46e98d422651..b480317a81b1 100644
--- a/core/modules/update/update.compare.inc
+++ b/core/modules/update/update.compare.inc
@@ -6,7 +6,7 @@
*/
/**
- * Fetch an array of installed and enabled projects.
+ * Fetches an array of installed and enabled projects.
*
* This is only responsible for generating an array of projects (taking into
* account projects that include more than one module or theme). Other
@@ -15,14 +15,39 @@
* that logic is only required when preparing the status report, not for
* fetching the available release data.
*
- * This array is fairly expensive to construct, since it involves a lot of
- * disk I/O, so we cache the results into the {cache_update} table using the
- * 'update_project_projects' cache ID. However, since this is not the data
- * about available updates fetched from the network, it is ok to invalidate it
- * somewhat quickly. If we keep this data for very long, site administrators
- * are more likely to see incorrect results if they upgrade to a newer version
- * of a module or theme but do not visit certain pages that automatically
- * clear this cache.
+ * This array is fairly expensive to construct, since it involves a lot of disk
+ * I/O, so we cache the results into the {cache_update} table using the
+ * 'update_project_projects' cache ID. However, since this is not the data about
+ * available updates fetched from the network, it is acceptable to invalidate it
+ * somewhat quickly. If we keep this data for very long, site administrators are
+ * more likely to see incorrect results if they upgrade to a newer version of a
+ * module or theme but do not visit certain pages that automatically clear this
+ * cache.
+ *
+ * @return
+ * An associative array of currently enabled projects keyed by the
+ * machine-readable project short name. Each project contains:
+ * - name: The machine-readable project short name.
+ * - info: An array with values from the main .info file for this project.
+ * - name: The human-readable name of the project.
+ * - package: The package that the project is grouped under.
+ * - version: The version of the project.
+ * - project: The Drupal.org project name.
+ * - datestamp: The date stamp of the project's main .info file.
+ * - _info_file_ctime: The maximum file change time for all of the .info
+ * files included in this project.
+ * - datestamp: The date stamp when the project was released, if known.
+ * - includes: An associative array containing all projects included with this
+ * project, keyed by the machine-readable short name with the human-readable
+ * name as value.
+ * - project_type: The type of project. Allowed values are 'module' and
+ * 'theme'.
+ * - project_status: This indicates if the project is enabled and will always
+ * be TRUE, as the function only returns enabled projects.
+ * - sub_themes: If the project is a theme it contains an associative array of
+ * all sub-themes.
+ * - base_themes: If the project is a theme it contains an associative array
+ * of all base-themes.
*
* @see update_process_project_info()
* @see update_calculate_project_data()
@@ -53,30 +78,31 @@ function update_get_projects() {
}
/**
- * Populate an array of project data.
- *
- * This iterates over a list of the installed modules or themes and groups
- * them by project and status. A few parts of this function assume that
- * enabled modules and themes are always processed first, and if disabled
- * modules or themes are being processed (there is a setting to control if
- * disabled code should be included in the Available updates report or not),
- * those are only processed after $projects has been populated with
- * information about the enabled code. 'Hidden' modules and themes are always
- * ignored. This function also records the latest change time on the .info
- * files for each module or theme, which is important data which is used when
- * deciding if the cached available update data should be invalidated.
+ * Populates an array of project data.
+ *
+ * This iterates over a list of the installed modules or themes and groups them
+ * by project and status. A few parts of this function assume that enabled
+ * modules and themes are always processed first, and if disabled modules or
+ * themes are being processed (there is a setting to control if disabled code
+ * should be included or not in the 'Available updates' report), those are only
+ * processed after $projects has been populated with information about the
+ * enabled code. Modules and themes set as hidden are always ignored. This
+ * function also records the latest change time on the .info files for each
+ * module or theme, which is important data which is used when deciding if the
+ * cached available update data should be invalidated.
*
* @param $projects
* Reference to the array of project data of what's installed on this site.
* @param $list
* Array of data to process to add the relevant info to the $projects array.
* @param $project_type
- * The kind of data in the list (can be 'module' or 'theme').
+ * The kind of data in the list. Can be 'module' or 'theme'.
* @param $status
* Boolean that controls what status (enabled or disabled) to process out of
* the $list and add to the $projects array.
* @param $additional_whitelist
- * Array of additional elements to be collected from the .info file.
+ * (optional) Array of additional elements to be collected from the .info
+ * file. Defaults to array().
*
* @see update_get_projects()
*/
@@ -213,8 +239,13 @@ function update_process_info_list(&$projects, $list, $project_type, $status, $ad
}
/**
- * Given a $file object (as returned by system_get_files_database()), figure
- * out what project it belongs to.
+ * Determines what project a given file object belongs to.
+ *
+ * @param $file
+ * A file object as returned by system_get_files_database().
+ *
+ * @return
+ * The canonical project short name.
*
* @see system_get_files_database()
*/
@@ -230,7 +261,9 @@ function update_get_project_name($file) {
}
/**
- * Process the list of projects on the system to figure out the currently
+ * Determines version and type information for currently installed projects.
+ *
+ * Processes the list of projects on the system to figure out the currently
* installed versions, and other information that is required before we can
* compare against the available releases to produce the status report.
*
@@ -279,7 +312,7 @@ function update_process_project_info(&$projects) {
}
/**
- * Calculate the current update status of all projects on the site.
+ * Calculates the current update status of all projects on the site.
*
* The results of this function are expensive to compute, especially on sites
* with lots of modules or themes, since it involves a lot of comparisons and
@@ -287,13 +320,16 @@ function update_process_project_info(&$projects) {
* table using the 'update_project_data' cache ID. However, since this is not
* the data about available updates fetched from the network, it is ok to
* invalidate it somewhat quickly. If we keep this data for very long, site
- * administrators are more likely to see incorrect results if they upgrade to
- * a newer version of a module or theme but do not visit certain pages that
+ * administrators are more likely to see incorrect results if they upgrade to a
+ * newer version of a module or theme but do not visit certain pages that
* automatically clear this cache.
*
* @param array $available
* Data about available project releases.
*
+ * @return
+ * An array of installed projects with current update status information.
+ *
* @see update_get_available()
* @see update_get_projects()
* @see update_process_project_info()
@@ -329,52 +365,50 @@ function update_calculate_project_data($available) {
}
/**
- * Calculate the current update status of a specific project.
+ * Calculates the current update status of a specific project.
*
- * This function is the heart of the update status feature. For each project
- * it is invoked with, it first checks if the project has been flagged with a
+ * This function is the heart of the update status feature. For each project it
+ * is invoked with, it first checks if the project has been flagged with a
* special status like "unsupported" or "insecure", or if the project node
* itself has been unpublished. In any of those cases, the project is marked
* with an error and the next project is considered.
*
* If the project itself is valid, the function decides what major release
* series to consider. The project defines what the currently supported major
- * versions are for each version of core, so the first step is to make sure
- * the current version is still supported. If so, that's the target version.
- * If the current version is unsupported, the project maintainer's recommended
- * major version is used. There's also a check to make sure that this function
- * never recommends an earlier release than the currently installed major
- * version.
- *
- * Given a target major version, it scans the available releases looking for
+ * versions are for each version of core, so the first step is to make sure the
+ * current version is still supported. If so, that's the target version. If the
+ * current version is unsupported, the project maintainer's recommended major
+ * version is used. There's also a check to make sure that this function never
+ * recommends an earlier release than the currently installed major version.
+ *
+ * Given a target major version, the available releases are scanned looking for
* the specific release to recommend (avoiding beta releases and development
- * snapshots if possible). This is complicated to describe, but an example
- * will help clarify. For the target major version, find the highest patch
- * level. If there is a release at that patch level with no extra ("beta",
- * etc), then we recommend the release at that patch level with the most
- * recent release date. If every release at that patch level has extra (only
- * betas), then recommend the latest release from the previous patch
- * level. For example:
+ * snapshots if possible). For the target major version, the highest patch level
+ * is found. If there is a release at that patch level with no extra ("beta",
+ * etc.), then the release at that patch level with the most recent release date
+ * is recommended. If every release at that patch level has extra (only betas),
+ * then the latest release from the previous patch level is recommended. For
+ * example:
*
- * 1.6-bugfix <-- recommended version because 1.6 already exists.
- * 1.6
+ * - 1.6-bugfix <-- recommended version because 1.6 already exists.
+ * - 1.6
*
* or
*
- * 1.6-beta
- * 1.5 <-- recommended version because no 1.6 exists.
- * 1.4
+ * - 1.6-beta
+ * - 1.5 <-- recommended version because no 1.6 exists.
+ * - 1.4
*
- * It also looks for the latest release from the same major version, even a
- * beta release, to display to the user as the "Latest version" option.
- * Additionally, it finds the latest official release from any higher major
- * versions that have been released to provide a set of "Also available"
+ * Also, the latest release from the same major version is looked for, even beta
+ * releases, to display to the user as the "Latest version" option.
+ * Additionally, the latest official release from any higher major versions that
+ * have been released is searched for to provide a set of "Also available"
* options.
*
- * Finally, and most importantly, it keeps scanning the release history until
- * it gets to the currently installed release, searching for anything marked
- * as a security update. If any security updates have been found between the
- * recommended release and the installed version, all of the releases that
+ * Finally, and most importantly, the release history continues to be scanned
+ * until the currently installed release is reached, searching for anything
+ * marked as a security update. If any security updates have been found between
+ * the recommended release and the installed version, all of the releases that
* included a security fix are recorded so that the site administrator can be
* warned their site is insecure, and links pointing to the release notes for
* each security update can be included (which, in turn, will link to the
@@ -383,9 +417,13 @@ function update_calculate_project_data($available) {
* This function relies on the fact that the .xml release history data comes
* sorted based on major version and patch level, then finally by release date
* if there are multiple releases such as betas from the same major.patch
- * version (e.g. 5.x-1.5-beta1, 5.x-1.5-beta2, and 5.x-1.5). Development
+ * version (e.g., 5.x-1.5-beta1, 5.x-1.5-beta2, and 5.x-1.5). Development
* snapshots for a given major version are always listed last.
*
+ * @param $project_data
+ * An array containing information about a specific project.
+ * @param $available
+ * Data about available project releases of a specific project.
*/
function update_calculate_project_update_status(&$project_data, $available) {
foreach (array('title', 'link') as $attribute) {
@@ -709,16 +747,16 @@ function update_calculate_project_update_status(&$project_data, $available) {
}
/**
- * Retrieve data from {cache_update} or empty the cache when necessary.
+ * Retrieves data from {cache_update} or empties the cache when necessary.
*
* Two very expensive arrays computed by this module are the list of all
- * installed modules and themes (and .info data, project associations, etc),
- * and the current status of the site relative to the currently available
- * releases. These two arrays are cached in the {cache_update} table and used
- * whenever possible. The cache is cleared whenever the administrator visits
- * the status report, available updates report, or the module or theme
- * administration pages, since we should always recompute the most current
- * values on any of those pages.
+ * installed modules and themes (and .info data, project associations, etc), and
+ * the current status of the site relative to the currently available releases.
+ * These two arrays are cached in the {cache_update} table and used whenever
+ * possible. The cache is cleared whenever the administrator visits the status
+ * report, available updates report, or the module or theme administration
+ * pages, since we should always recompute the most current values on any of
+ * those pages.
*
* Note: while both of these arrays are expensive to compute (in terms of disk
* I/O and some fairly heavy CPU processing), neither of these is the actual
@@ -728,13 +766,13 @@ function update_calculate_project_update_status(&$project_data, $available) {
* hour and never get invalidated just by visiting a page on the site.
*
* @param $cid
- * The cache id of data to return from the cache. Valid options are
+ * The cache ID of data to return from the cache. Valid options are
* 'update_project_data' and 'update_project_projects'.
*
* @return
* The cached value of the $projects array generated by
- * update_calculate_project_data() or update_get_projects(), or an empty
- * array when the cache is cleared.
+ * update_calculate_project_data() or update_get_projects(), or an empty array
+ * when the cache is cleared.
*/
function update_project_cache($cid) {
$projects = array();
@@ -765,15 +803,16 @@ function update_project_cache($cid) {
}
/**
- * Filter the project .info data to only save attributes we need.
+ * Filters the project .info data to only save attributes we need.
*
* @param array $info
* Array of .info file data as returned by drupal_parse_info_file().
* @param $additional_whitelist
- * Array of additional elements to be collected from the .info file.
+ * (optional) Array of additional elements to be collected from the .info
+ * file. Defaults to array().
*
* @return
- * Array of .info file data we need for the Update manager.
+ * Array of .info file data we need for the update manager.
*
* @see update_process_info_list()
*/
diff --git a/core/modules/update/update.css b/core/modules/update/update.css
index 80d0bdbb0f64..cb2050040cdc 100644
--- a/core/modules/update/update.css
+++ b/core/modules/update/update.css
@@ -1,3 +1,7 @@
+/**
+ * @file
+ * Styles used by the Update Manager module.
+ */
.update .project {
font-weight: bold;
diff --git a/core/modules/update/update.fetch.inc b/core/modules/update/update.fetch.inc
index 4d8e3c2aad4f..92f4cc14b270 100644
--- a/core/modules/update/update.fetch.inc
+++ b/core/modules/update/update.fetch.inc
@@ -6,7 +6,11 @@
*/
/**
- * Callback to manually check the update status without cron.
+ * Page callback: Checks for updates and displays the update status report.
+ *
+ * Manually checks the update status without the use of cron.
+ *
+ * @see update_menu()
*/
function update_manual_status() {
_update_refresh();
@@ -25,7 +29,10 @@ function update_manual_status() {
}
/**
- * Process a step in the batch for fetching available update data.
+ * Batch callback: Processes a step in batch for fetching available update data.
+ *
+ * @param $context
+ * Reference to an array used for Batch API storage.
*/
function update_fetch_data_batch(&$context) {
$queue = queue('update_fetch_tasks');
@@ -70,12 +77,12 @@ function update_fetch_data_batch(&$context) {
}
/**
- * Batch API callback when all fetch tasks have been completed.
+ * Batch callback: Performs actions when all fetch tasks have been completed.
*
* @param $success
- * Boolean indicating the success of the batch.
+ * TRUE if the batch operation was successful; FALSE if there were errors.
* @param $results
- * Associative array holding the results of the batch, including the key
+ * An associative array of results from the batch operation, including the key
* 'updated' which holds the total number of projects we fetched available
* update data for.
*/
@@ -96,7 +103,7 @@ function update_fetch_data_finished($success, $results) {
}
/**
- * Attempt to drain the queue of tasks for release history data to fetch.
+ * Attempts to drain the queue of tasks for release history data to fetch.
*/
function _update_fetch_data() {
$queue = queue('update_fetch_tasks');
@@ -108,13 +115,14 @@ function _update_fetch_data() {
}
/**
- * Process a task to fetch available update data for a single project.
+ * Processes a task to fetch available update data for a single project.
*
- * Once the release history XML data is downloaded, it is parsed and saved
- * into the {cache_update} table in an entry just for that project.
+ * Once the release history XML data is downloaded, it is parsed and saved into
+ * the {cache_update} table in an entry just for that project.
*
* @param $project
* Associative array of information about the project to fetch data for.
+ *
* @return
* TRUE if we fetched parsable XML, otherwise FALSE.
*/
@@ -187,7 +195,7 @@ function _update_process_fetch_task($project) {
}
/**
- * Clear out all the cached available update data and initiate re-fetching.
+ * Clears out all the cached available update data and initiates re-fetching.
*/
function _update_refresh() {
module_load_include('inc', 'update', 'update.compare');
@@ -214,7 +222,7 @@ function _update_refresh() {
}
/**
- * Add a task to the queue for fetching release history data for a project.
+ * Adds a task to the queue for fetching release history data for a project.
*
* We only create a new fetch task if there's no task already in the queue for
* this particular project (based on 'fetch_task::' entries in the
@@ -222,8 +230,8 @@ function _update_refresh() {
*
* @param $project
* Associative array of information about a project as created by
- * update_get_projects(), including keys such as 'name' (short name),
- * and the 'info' array with data from a .info file for the project.
+ * update_get_projects(), including keys such as 'name' (short name), and the
+ * 'info' array with data from a .info file for the project.
*
* @see update_get_projects()
* @see update_get_available()
@@ -263,14 +271,17 @@ function _update_create_fetch_task($project) {
/**
* Generates the URL to fetch information about project updates.
*
- * This figures out the right URL to use, based on the project's .info file
- * and the global defaults. Appends optional query arguments when the site is
+ * This figures out the right URL to use, based on the project's .info file and
+ * the global defaults. Appends optional query arguments when the site is
* configured to report usage stats.
*
* @param $project
* The array of project information from update_get_projects().
* @param $site_key
- * The anonymous site key hash (optional).
+ * (optional) The anonymous site key hash. Defaults to an empty string.
+ *
+ * @return
+ * The URL for fetching information about updates to the specified project.
*
* @see update_fetch_data()
* @see _update_process_fetch_task()
@@ -304,10 +315,11 @@ function _update_build_fetch_url($project, $site_key = '') {
}
/**
- * Return the base of the URL to fetch available update data for a project.
+ * Returns the base of the URL to fetch available update data for a project.
*
* @param $project
* The array of project information from update_get_projects().
+ *
* @return
* The base of the URL used for fetching available update data. This does
* not include the path elements to specify a particular project, version,
@@ -320,10 +332,10 @@ function _update_get_fetch_url_base($project) {
}
/**
- * Perform any notifications that should be done once cron fetches new data.
+ * Performs any notifications that should be done once cron fetches new data.
*
- * This method checks the status of the site using the new data and depending
- * on the configuration of the site, notifies administrators via email if there
+ * This method checks the status of the site using the new data and, depending
+ * on the configuration of the site, notifies administrators via e-mail if there
* are new releases or missing security updates.
*
* @see update_requirements()
@@ -358,7 +370,7 @@ function _update_cron_notify() {
}
/**
- * Parse the XML of the Drupal release history info files.
+ * Parses the XML of the Drupal release history info files.
*
* @param $raw_xml
* A raw XML string of available release data for a given project.
diff --git a/core/modules/update/update.install b/core/modules/update/update.install
index 9ff39d126b05..406b9aefc451 100644
--- a/core/modules/update/update.install
+++ b/core/modules/update/update.install
@@ -2,26 +2,25 @@
/**
* @file
- * Install, update and uninstall functions for the update module.
+ * Install, update, and uninstall functions for the Update Manager module.
*/
/**
* Implements hook_requirements().
*
* @return
- * An array describing the status of the site regarding available updates.
- * If there is no update data, only one record will be returned, indicating
- * that the status of core can't be determined. If data is available, there
- * will be two records: one for core, and another for all of contrib
- * (assuming there are any contributed modules or themes enabled on the
- * site). In addition to the fields expected by hook_requirements ('value',
- * 'severity', and optionally 'description'), this array will contain a
- * 'reason' attribute, which is an integer constant to indicate why the
- * given status is being returned (UPDATE_NOT_SECURE, UPDATE_NOT_CURRENT, or
- * UPDATE_UNKNOWN). This is used for generating the appropriate e-mail
- * notification messages during update_cron(), and might be useful for other
- * modules that invoke update_requirements() to find out if the site is up
- * to date or not.
+ * An array describing the status of the site regarding available updates. If
+ * there is no update data, only one record will be returned, indicating that
+ * the status of core can't be determined. If data is available, there will be
+ * two records: one for core, and another for all of contrib (assuming there
+ * are any contributed modules or themes enabled on the site). In addition to
+ * the fields expected by hook_requirements ('value', 'severity', and
+ * optionally 'description'), this array will contain a 'reason' attribute,
+ * which is an integer constant to indicate why the given status is being
+ * returned (UPDATE_NOT_SECURE, UPDATE_NOT_CURRENT, or UPDATE_UNKNOWN). This
+ * is used for generating the appropriate e-mail notification messages during
+ * update_cron(), and might be useful for other modules that invoke
+ * update_requirements() to find out if the site is up to date or not.
*
* @see _update_message_text()
* @see _update_cron_notify()
@@ -96,19 +95,19 @@ function update_uninstall() {
}
/**
- * Private helper method to fill in the requirements array.
+ * Fills in the requirements array.
*
* This is shared for both core and contrib to generate the right elements in
* the array for hook_requirements().
*
* @param $project
- * Array of information about the project we're testing as returned by
- * update_calculate_project_data().
+ * Array of information about the project we're testing as returned by
+ * update_calculate_project_data().
* @param $type
- * What kind of project is this ('core' or 'contrib').
+ * What kind of project this is ('core' or 'contrib').
*
* @return
- * An array to be included in the nested $requirements array.
+ * An array to be included in the nested $requirements array.
*
* @see hook_requirements()
* @see update_requirements()
diff --git a/core/modules/update/update.manager.inc b/core/modules/update/update.manager.inc
index f7881d483196..1e4a3d506484 100644
--- a/core/modules/update/update.manager.inc
+++ b/core/modules/update/update.manager.inc
@@ -2,7 +2,8 @@
/**
* @file
- * Administrative screens and processing functions for the update manager.
+ * Administrative screens and processing functions of the Update Manager module.
+ *
* This allows site administrators with the 'administer software updates'
* permission to either upgrade existing projects, or download and install new
* ones, so long as the killswitch setting ('allow_authorize_operations') is
@@ -11,54 +12,55 @@
* To install new code, the administrator is prompted for either the URL of an
* archive file, or to directly upload the archive file. The archive is loaded
* into a temporary location, extracted, and verified. If everything is
- * successful, the user is redirected to authorize.php to type in their file
- * transfer credentials and authorize the installation to proceed with
- * elevated privileges, such that the extracted files can be copied out of the
- * temporary location and into the live web root.
+ * successful, the user is redirected to authorize.php to type in file transfer
+ * credentials and authorize the installation to proceed with elevated
+ * privileges, such that the extracted files can be copied out of the temporary
+ * location and into the live web root.
*
* Updating existing code is a more elaborate process. The first step is a
- * selection form where the user is presented with a table of installed
- * projects that are missing newer releases. The user selects which projects
- * they wish to upgrade, and presses the "Download updates" button to
- * continue. This sets up a batch to fetch all the selected releases, and
- * redirects to admin/update/download to display the batch progress bar as it
- * runs. Each batch operation is responsible for downloading a single file,
- * extracting the archive, and verifying the contents. If there are any
- * errors, the user is redirected back to the first page with the error
- * messages. If all downloads were extacted and verified, the user is instead
- * redirected to admin/update/ready, a landing page which reminds them to
- * backup their database and asks if they want to put the site offline during
- * the upgrade. Once the user presses the "Install updates" button, they are
- * redirected to authorize.php to supply their web root file access
- * credentials. The authorized operation (which lives in update.authorize.inc)
- * sets up a batch to copy each extracted update from the temporary location
- * into the live web root.
+ * selection form where the user is presented with a table of installed projects
+ * that are missing newer releases. The user selects which projects they wish to
+ * update, and presses the "Download updates" button to continue. This sets up a
+ * batch to fetch all the selected releases, and redirects to
+ * admin/update/download to display the batch progress bar as it runs. Each
+ * batch operation is responsible for downloading a single file, extracting the
+ * archive, and verifying the contents. If there are any errors, the user is
+ * redirected back to the first page with the error messages. If all downloads
+ * were extacted and verified, the user is instead redirected to
+ * admin/update/ready, a landing page which reminds them to backup their
+ * database and asks if they want to put the site offline during the update.
+ * Once the user presses the "Install updates" button, they are redirected to
+ * authorize.php to supply their web root file access credentials. The
+ * authorized operation (which lives in update.authorize.inc) sets up a batch to
+ * copy each extracted update from the temporary location into the live web
+ * root.
*/
use Drupal\Core\Updater\Updater;
use Drupal\Core\FileTransfer\Local;
/**
- * @defgroup update_manager_update Update manager: update
+ * @defgroup update_manager_update Update Manager module: update
* @{
- * Update manager for updating existing code.
+ * Update Manager module functionality for updating existing code.
*
* Provides a user interface to update existing code.
*/
/**
- * Build the form for the update manager page to update existing projects.
+ * Form constructor for the update form of the Update Manager module.
*
* This presents a table with all projects that have available updates with
* checkboxes to select which ones to upgrade.
*
- * @param $form
- * @param $form_state
* @param $context
- * String representing the context from which we're trying to update, can be:
- * 'module', 'theme' or 'report'.
- * @return
- * The form array for selecting which projects to update.
+ * String representing the context from which we're trying to update.
+ * Allowed values are 'module', 'theme', and 'report'.
+ *
+ * @see update_manager_update_form_validate()
+ * @see update_manager_update_form_submit()
+ * @see update_menu()
+ * @ingroup forms
*/
function update_manager_update_form($form, $form_state = array(), $context) {
if (!_update_manager_check_backends($form, 'update')) {
@@ -266,7 +268,7 @@ function update_manager_update_form($form, $form_state = array(), $context) {
}
/**
- * Returns HTML for the first page in the update manager wizard to select projects.
+ * Returns HTML for the first page in the process of updating projects.
*
* @param $variables
* An associative array containing:
@@ -283,7 +285,11 @@ function theme_update_manager_update_form($variables) {
}
/**
- * Validation callback to ensure that at least one project is selected.
+ * Form validation handler for update_manager_update_form().
+ *
+ * Ensures that at least one project is selected.
+ *
+ * @see update_manager_update_form_submit()
*/
function update_manager_update_form_validate($form, &$form_state) {
if (!empty($form_state['values']['projects'])) {
@@ -298,11 +304,11 @@ function update_manager_update_form_validate($form, &$form_state) {
}
/**
- * Submit function for the main update form.
+ * Form submission handler for update_manager_update_form().
*
- * This sets up a batch to download, extract and verify the selected releases
+ * Sets up a batch that downloads, extracts, and verifies the selected releases.
*
- * @see update_manager_update_form()
+ * @see update_manager_update_form_validate()
*/
function update_manager_update_form_submit($form, &$form_state) {
$projects = array();
@@ -332,7 +338,12 @@ function update_manager_update_form_submit($form, &$form_state) {
}
/**
- * Batch callback invoked when the download batch is completed.
+ * Batch callback: Performs actions when the download batch is completed.
+ *
+ * @param $success
+ * TRUE if the batch operation was successful, FALSE if there were errors.
+ * @param $results
+ * An associative array of results from the batch operation.
*/
function update_manager_download_batch_finished($success, $results) {
if (!empty($results['errors'])) {
@@ -355,15 +366,21 @@ function update_manager_download_batch_finished($success, $results) {
}
/**
+ * Form constructor for the update ready form.
+ *
* Build the form when the site is ready to update (after downloading).
*
* This form is an intermediary step in the automated update workflow. It is
- * presented to the site administrator after all the required updates have
- * been downloaded and verified. The point of this page is to encourage the
- * user to backup their site, gives them the opportunity to put the site
- * offline, and then asks them to confirm that the update should continue.
- * After this step, the user is redirected to authorize.php to enter their
- * file transfer credentials and attempt to complete the update.
+ * presented to the site administrator after all the required updates have been
+ * downloaded and verified. The point of this page is to encourage the user to
+ * backup their site, give them the opportunity to put the site offline, and
+ * then ask them to confirm that the update should continue. After this step,
+ * the user is redirected to authorize.php to enter their file transfer
+ * credentials and attempt to complete the update.
+ *
+ * @see update_manager_update_ready_form_submit()
+ * @see update_menu()
+ * @ingroup forms
*/
function update_manager_update_ready_form($form, &$form_state) {
if (!_update_manager_check_backends($form, 'update')) {
@@ -392,14 +409,13 @@ function update_manager_update_ready_form($form, &$form_state) {
}
/**
- * Submit handler for the form to confirm that an update should continue.
+ * Form submission handler for update_manager_update_ready_form().
*
* If the site administrator requested that the site is put offline during the
- * update, do so now. Otherwise, pull information about all the required
- * updates out of the SESSION, figure out what Drupal\Core\Updater\Updater class
- * is needed for each one, generate an array of update operations to perform,
- * and hand it all off to system_authorized_init(), then redirect to
- * authorize.php.
+ * update, do so now. Otherwise, pull information about all the required updates
+ * out of the SESSION, figure out what Drupal\Core\Updater\Updater class is
+ * needed for each one, generate an array of update operations to perform, and
+ * hand it all off to system_authorized_init(), then redirect to authorize.php.
*
* @see update_authorize_run_update()
* @see system_authorized_init()
@@ -458,26 +474,27 @@ function update_manager_update_ready_form_submit($form, &$form_state) {
*/
/**
- * @defgroup update_manager_install Update manager: install
+ * @defgroup update_manager_install Update Manager module: install
* @{
- * Update manager for installing new code.
+ * Update Manager module functionality for installing new code.
*
* Provides a user interface to install new code.
*/
/**
- * Build the form for the update manager page to install new projects.
+ * Form constructor for the install form of the Update Manager module.
*
* This presents a place to enter a URL or upload an archive file to use to
* install a new module or theme.
*
- * @param $form
- * @param $form_state
* @param $context
- * String representing the context from which we're trying to install, can
- * be: 'module', 'theme' or 'report'.
- * @return
- * The form array for selecting which project to install.
+ * String representing the context from which we're trying to install.
+ * Allowed values are 'module', 'theme', and 'report'.
+ *
+ * @see update_manager_install_form_validate()
+ * @see update_manager_install_form_submit()
+ * @see update_menu()
+ * @ingroup forms
*/
function update_manager_install_form($form, &$form_state, $context) {
if (!_update_manager_check_backends($form, 'install')) {
@@ -528,11 +545,11 @@ function update_manager_install_form($form, &$form_state, $context) {
* @param array $form
* Reference to the form array we're building.
* @param string $operation
- * The Update manager operation we're in the middle of. Can be either
- * 'update' or 'install'. Use to provide operation-specific interface text.
+ * The update manager operation we're in the middle of. Can be either 'update'
+ * or 'install'. Use to provide operation-specific interface text.
*
* @return
- * TRUE if the Update manager should continue to the next step in the
+ * TRUE if the update manager should continue to the next step in the
* workflow, or FALSE if we've hit a fatal configuration and must halt the
* workflow.
*/
@@ -590,7 +607,9 @@ function _update_manager_check_backends(&$form, $operation) {
}
/**
- * Validate the form for installing a new project via the update manager.
+ * Form validation handler for update_manager_install_form().
+ *
+ * @see update_manager_install_form_submit()
*/
function update_manager_install_form_validate($form, &$form_state) {
if (!($form_state['values']['project_url'] XOR !empty($_FILES['files']['name']['project_upload']))) {
@@ -599,7 +618,7 @@ function update_manager_install_form_validate($form, &$form_state) {
}
/**
- * Handle form submission when installing new projects via the update manager.
+ * Form submission handler for update_manager_install_form().
*
* Either downloads the file specified in the URL to a temporary cache, or
* uploads the file attached to the form, then attempts to extract the archive
@@ -609,6 +628,7 @@ function update_manager_install_form_validate($form, &$form_state) {
* operation to run via authorize.php which will copy the extracted files from
* the temporary location into the live site.
*
+ * @see update_manager_install_form_validate()
* @see update_authorize_run_install()
* @see system_authorized_init()
* @see system_authorized_get_url()
@@ -726,26 +746,26 @@ function update_manager_install_form_submit($form, &$form_state) {
*/
/**
- * @defgroup update_manager_file Update manager: file management
+ * @defgroup update_manager_file Update Manager module: file management
* @{
- * Update manager file management functions.
+ * Update Manager module file management functions.
*
- * These functions are used by the update manager to copy, extract
- * and verify archive files.
+ * These functions are used by the update manager to copy, extract, and verify
+ * archive files.
*/
/**
- * Unpack a downloaded archive file.
+ * Unpacks a downloaded archive file.
*
- * @param string $project
- * The short name of the project to download.
* @param string $file
* The filename of the archive you wish to extract.
* @param string $directory
* The directory you wish to extract the archive into.
+ *
* @return Archiver
* The Archiver object used to extract the archive.
- * @throws Exception on failure.
+ *
+ * @throws Exception
*/
function update_manager_archive_extract($file, $directory) {
$archiver = archiver_get_archiver($file);
@@ -773,7 +793,7 @@ function update_manager_archive_extract($file, $directory) {
}
/**
- * Verify an archive after it has been downloaded and extracted.
+ * Verifies an archive after it has been downloaded and extracted.
*
* This function is responsible for invoking hook_verify_update_archive().
*
@@ -785,18 +805,17 @@ function update_manager_archive_extract($file, $directory) {
* The directory that the archive was extracted into.
*
* @return array
- * An array of error messages to display if the archive was invalid. If
- * there are no errors, it will be an empty array.
- *
+ * An array of error messages to display if the archive was invalid. If there
+ * are no errors, it will be an empty array.
*/
function update_manager_archive_verify($project, $archive_file, $directory) {
return module_invoke_all('verify_update_archive', $project, $archive_file, $directory);
}
/**
- * Copies a file from $url to the temporary directory for updates.
+ * Copies a file from the specified URL to the temporary directory for updates.
*
- * If the file has already been downloaded, returns the the local path.
+ * Returns the local path if the file has already been downloaded.
*
* @param $url
* The URL of the file on the server.
@@ -825,18 +844,18 @@ function update_manager_file_get($url) {
}
/**
- * Batch operation: download, unpack, and verify a project.
+ * Batch callback: Downloads, unpacks, and verifies a project.
*
- * This function assumes that the provided URL points to a file archive of
- * some sort. The URL can have any scheme that we have a file stream wrapper
- * to support. The file is downloaded to a local cache.
+ * This function assumes that the provided URL points to a file archive of some
+ * sort. The URL can have any scheme that we have a file stream wrapper to
+ * support. The file is downloaded to a local cache.
*
* @param string $project
* The short name of the project to download.
* @param string $url
* The URL to download a specific project release archive file.
* @param array $context
- * Reference to an array used for BatchAPI storage.
+ * Reference to an array used for Batch API storage.
*
* @see update_manager_download_page()
*/
@@ -885,8 +904,8 @@ function update_manager_batch_project_get($project, $url, &$context) {
* Determines if file transfers will be performed locally.
*
* If the server is configured such that webserver-created files have the same
- * owner as the configuration directory (e.g. sites/default) where new code
- * will eventually be installed, the Update manager can transfer files entirely
+ * owner as the configuration directory (e.g., sites/default) where new code
+ * will eventually be installed, the update manager can transfer files entirely
* locally, without changing their ownership (in other words, without prompting
* the user for FTP, SSH or other credentials).
*
diff --git a/core/modules/update/update.module b/core/modules/update/update.module
index 4b3eab29c82f..4f787cd342de 100644
--- a/core/modules/update/update.module
+++ b/core/modules/update/update.module
@@ -2,10 +2,13 @@
/**
* @file
- * The "Update status" module checks for available updates of Drupal core and
- * any installed contributed modules and themes. It warns site administrators
- * if newer releases are available via the system status report
- * (admin/reports/status), the module and theme pages, and optionally via email.
+ * Handles updates of Drupal core and contributed projects.
+ *
+ * The module checks for available updates of Drupal core and any installed
+ * contributed modules and themes. It warns site administrators if newer
+ * releases are available via the system status report (admin/reports/status),
+ * the module and theme pages, and optionally via e-mail. It also provides the
+ * ability to install contributed modules and themes via an user interface.
*/
/**
@@ -246,11 +249,14 @@ function update_menu() {
}
/**
- * Determine if the current user can access the updater menu items.
+ * Access callback: Resolves if the current user can access updater menu items.
+ *
+ * It both enforces the 'administer software updates' permission and the global
+ * kill switch for the authorize.php script.
*
- * This is used as a menu system access callback. It both enforces the
- * 'administer software updates' permission and the global killswitch for the
- * authorize.php script.
+ * @return
+ * TRUE if the current user can access the updater menu items; FALSE
+ * otherwise.
*
* @see update_menu()
*/
@@ -327,10 +333,10 @@ function update_themes_disabled($themes) {
}
/**
- * Implements hook_form_FORM_ID_alter().
+ * Implements hook_form_FORM_ID_alter() for system_modules().
*
- * Adds a submit handler to the system modules form, so that if a site admin
- * saves the form, we invalidate the cache of available updates.
+ * Adds a form submission handler to the system modules form, so that if a site
+ * admin saves the form, we invalidate the cache of available updates.
*
* @see _update_cache_clear()
*/
@@ -339,7 +345,9 @@ function update_form_system_modules_alter(&$form, $form_state) {
}
/**
- * Helper function for use as a form submit callback.
+ * Form submission handler for system_modules().
+ *
+ * @see update_form_system_modules_alter()
*/
function update_cache_clear_submit($form, &$form_state) {
// Clear all update module caches.
@@ -347,7 +355,7 @@ function update_cache_clear_submit($form, &$form_state) {
}
/**
- * Prints a warning message when there is no data about available updates.
+ * Returns a warning message when there is no data about available updates.
*/
function _update_no_data() {
$destination = drupal_get_destination();
@@ -358,20 +366,22 @@ function _update_no_data() {
}
/**
- * Internal helper to try to get the update information from the cache
- * if possible, and to refresh the cache when necessary.
+ * Tries to get update information from cache and refreshes it when necessary.
*
* In addition to checking the cache lifetime, this function also ensures that
* there are no .info files for enabled modules or themes that have a newer
* modification timestamp than the last time we checked for available update
- * data. If any .info file was modified, it almost certainly means a new
- * version of something was installed. Without fresh available update data,
- * the logic in update_calculate_project_data() will be wrong and produce
- * confusing, bogus results.
+ * data. If any .info file was modified, it almost certainly means a new version
+ * of something was installed. Without fresh available update data, the logic in
+ * update_calculate_project_data() will be wrong and produce confusing, bogus
+ * results.
*
* @param $refresh
- * Boolean to indicate if this method should refresh the cache automatically
- * if there's no data.
+ * (optional) Boolean to indicate if this method should refresh the cache
+ * automatically if there's no data. Defaults to FALSE.
+ *
+ * @return
+ * Array of data about available releases, keyed by project shortname.
*
* @see update_refresh()
* @see update_get_projects()
@@ -428,7 +438,11 @@ function update_get_available($refresh = FALSE) {
}
/**
- * Wrapper to load the include file and then create a new fetch task.
+ * Creates a new fetch task after loading the necessary include file.
+ *
+ * @param $project
+ * Associative array of information about a project. See update_get_projects()
+ * for the keys used.
*
* @see _update_create_fetch_task()
*/
@@ -438,7 +452,7 @@ function update_create_fetch_task($project) {
}
/**
- * Wrapper to load the include file and then refresh the release data.
+ * Refreshes the release data after loading the necessary include file.
*
* @see _update_refresh()
*/
@@ -448,7 +462,9 @@ function update_refresh() {
}
/**
- * Wrapper to load the include file and then attempt to fetch update data.
+ * Attempts to fetch update data after loading the necessary include file.
+ *
+ * @see _update_fetch_data()
*/
function update_fetch_data() {
module_load_include('inc', 'update', 'update.fetch');
@@ -456,7 +472,7 @@ function update_fetch_data() {
}
/**
- * Return all currently cached data about available releases for all projects.
+ * Returns all currently cached data about available releases for all projects.
*
* @return
* Array of data about available releases, keyed by project shortname.
@@ -481,17 +497,17 @@ function _update_get_cached_available_releases() {
/**
* Implements hook_mail().
*
- * Constructs the email notification message when the site is out of date.
+ * Constructs the e-mail notification message when the site is out of date.
*
* @param $key
* Unique key to indicate what message to build, always 'status_notify'.
* @param $message
* Reference to the message array being built.
* @param $params
- * Array of parameters to indicate what kind of text to include in the
- * message body. This is a keyed array of message type ('core' or 'contrib')
- * as the keys, and the status reason constant (UPDATE_NOT_SECURE, etc) for
- * the values.
+ * Array of parameters to indicate what kind of text to include in the message
+ * body. This is a keyed array of message type ('core' or 'contrib') as the
+ * keys, and the status reason constant (UPDATE_NOT_SECURE, etc) for the
+ * values.
*
* @see drupal_mail()
* @see _update_cron_notify()
@@ -518,22 +534,23 @@ function update_mail($key, &$message, $params) {
}
/**
- * Helper function to return the appropriate message text when the site is out
- * of date or missing a security update.
+ * Returns the appropriate message text when site is out of date or not secure.
*
* These error messages are shared by both update_requirements() for the
* site-wide status report at admin/reports/status and in the body of the
- * notification emails generated by update_cron().
+ * notification e-mail messages generated by update_cron().
*
* @param $msg_type
- * String to indicate what kind of message to generate. Can be either
- * 'core' or 'contrib'.
+ * String to indicate what kind of message to generate. Can be either 'core'
+ * or 'contrib'.
* @param $msg_reason
* Integer constant specifying why message is generated.
* @param $report_link
- * Boolean that controls if a link to the updates report should be added.
+ * (optional) Boolean that controls if a link to the updates report should be
+ * added. Defaults to FALSE.
* @param $language
- * An optional language object to use.
+ * (optional) A language object to use. Defaults to NULL.
+ *
* @return
* The properly translated error message for the given key.
*/
@@ -603,10 +620,9 @@ function _update_message_text($msg_type, $msg_reason, $report_link = FALSE, $lan
}
/**
- * Private sort function to order projects based on their status.
+ * Orders projects based on their status.
*
- * @see update_requirements()
- * @see uasort()
+ * Callback for uasort() within update_requirements().
*/
function _update_project_status_sort($a, $b) {
// The status constants are numerically in the right order, so we can
@@ -621,17 +637,16 @@ function _update_project_status_sort($a, $b) {
/**
* Returns HTML for the last time we checked for update data.
*
- * In addition to properly formating the given timestamp, this function also
+ * In addition to properly formatting the given timestamp, this function also
* provides a "Check manually" link that refreshes the available update and
* redirects back to the same page.
*
* @param $variables
* An associative array containing:
- * - 'last': The timestamp when the site last checked for available updates.
+ * - last: The timestamp when the site last checked for available updates.
*
* @see theme_update_report()
* @see theme_update_available_updates_form()
- *
* @ingroup themeable
*/
function theme_update_last_check($variables) {
@@ -647,7 +662,7 @@ function theme_update_last_check($variables) {
* Implements hook_verify_update_archive().
*
* First, we ensure that the archive isn't a copy of Drupal core, which the
- * Update manager does not yet support. @see http://drupal.org/node/606592
+ * update manager does not yet support. See http://drupal.org/node/606592
*
* Then, we make sure that at least one module included in the archive file has
* an .info file which claims that the code is compatible with the current
@@ -719,19 +734,19 @@ function update_verify_update_archive($project, $archive_file, $directory) {
* cleared when we're populating it after successfully fetching new available
* update data. Usage of the core cache API results in all sorts of potential
* problems that would result in attempting to fetch available update data all
- * the time, including if a site has a "minimum cache lifetime" (which is both
- * a minimum and a maximum) defined, or if a site uses memcache or another
- * plug-able cache system that assumes volatile caches.
+ * the time, including if a site has a "minimum cache lifetime" (which is both a
+ * minimum and a maximum) defined, or if a site uses memcache or another
+ * pluggable cache system that assumes volatile caches.
*
- * Update module still uses the {cache_update} table, but instead of using
- * the cache API, there are private helper functions that implement these same
- * basic tasks but ensure that the cache is not prematurely cleared, and that
- * the data is always stored in the database, even if memcache or another cache
- * backend is in use.
+ * The Update Manager module still uses the {cache_update} table, but instead of
+ * using the cache API, there are private helper functions that implement these
+ * same basic tasks but ensure that the cache is not prematurely cleared, and
+ * that the data is always stored in the database, even if memcache or another
+ * cache backend is in use.
*/
/**
- * Store data in the private update status cache table.
+ * Stores data in the private update status cache table.
*
* @param $cid
* The cache ID to save the data with.
@@ -743,6 +758,8 @@ function update_verify_update_archive($project, $archive_file, $directory) {
* by explicitly using _update_cache_clear().
* - A Unix timestamp: Indicates that the item should be kept at least until
* the given time, after which it will be invalidated.
+ *
+ * @see _update_cache_get()
*/
function _update_cache_set($cid, $data, $expire) {
$fields = array(
@@ -764,12 +781,15 @@ function _update_cache_set($cid, $data, $expire) {
}
/**
- * Retrieve data from the private update status cache table.
+ * Retrieves data from the private update status cache table.
*
* @param $cid
* The cache ID to retrieve.
+ *
* @return
- * The data for the given cache ID, or NULL if the ID was not found.
+ * An array of data for the given cache ID, or NULL if the ID was not found.
+ *
+ * @see _update_cache_set()
*/
function _update_cache_get($cid) {
$cache = db_query("SELECT data, created, expire, serialized FROM {cache_update} WHERE cid = :cid", array(':cid' => $cid))->fetchObject();
@@ -782,7 +802,10 @@ function _update_cache_get($cid) {
}
/**
- * Return an array of cache items with a given cache ID prefix.
+ * Returns an array of cache items with a given cache ID prefix.
+ *
+ * @param string $cid_prefix
+ * The cache ID prefix.
*
* @return
* Associative array of cache items, keyed by cache ID.
@@ -808,12 +831,12 @@ function _update_get_cache_multiple($cid_prefix) {
* Invalidates cached data relating to update status.
*
* @param $cid
- * Optional cache ID of the record to clear from the private update module
- * cache. If empty, all records will be cleared from the table except
- * fetch tasks.
+ * (optional) Cache ID of the record to clear from the private update module
+ * cache. If empty, all records will be cleared from the table except fetch
+ * tasks. Defaults to NULL.
* @param $wildcard
- * If $wildcard is TRUE, cache IDs starting with $cid are deleted in
- * addition to the exact cache ID specified by $cid.
+ * (optional) If TRUE, cache IDs starting with $cid are deleted in addition to
+ * the exact cache ID specified by $cid. Defaults to FALSE.
*/
function _update_cache_clear($cid = NULL, $wildcard = FALSE) {
if (empty($cid)) {
@@ -838,18 +861,18 @@ function _update_cache_clear($cid = NULL, $wildcard = FALSE) {
/**
* Implements hook_cache_flush().
*
- * Called from update.php (among others) to flush the caches.
- * Since we're running update.php, we are likely to install a new version of
- * something, in which case, we want to check for available update data again.
- * However, because we have our own caching system, we need to directly clear
- * the database table ourselves at this point and return nothing, for example,
- * on sites that use memcache where cache_clear_all() won't know how to purge
- * this data.
+ * Called from update.php (among others) to flush the caches. Since we're
+ * running update.php, we are likely to install a new version of something, in
+ * which case, we want to check for available update data again. However,
+ * because we have our own caching system, we need to directly clear the
+ * database table ourselves at this point and return nothing, for example, on
+ * sites that use memcache where cache_clear_all() won't know how to purge this
+ * data.
*
- * However, we only want to do this from update.php, since otherwise, we'd
- * lose all the available update data on every cron run. So, we specifically
- * check if the site is in MAINTENANCE_MODE == 'update' (which indicates
- * update.php is running, not update module... alas for overloaded names).
+ * However, we only want to do this from update.php, since otherwise, we'd lose
+ * all the available update data on every cron run. So, we specifically check if
+ * the site is in MAINTENANCE_MODE == 'update' (which indicates update.php is
+ * running, not update module... alas for overloaded names).
*/
function update_cache_flush() {
if (defined('MAINTENANCE_MODE') && MAINTENANCE_MODE == 'update') {
@@ -863,7 +886,7 @@ function update_cache_flush() {
*/
/**
- * Return a short unique identifier for this Drupal installation.
+ * Returns a short unique identifier for this Drupal installation.
*
* @return
* An eight character string uniquely identifying this Drupal installation.
@@ -877,14 +900,15 @@ function _update_manager_unique_identifier() {
}
/**
- * Return the directory where update archive files should be extracted.
+ * Returns the directory where update archive files should be extracted.
*
* @param $create
- * If TRUE, attempt to create the directory if it does not already exist.
+ * (optional) Whether to attempt to create the directory if it does not
+ * already exist. Defaults to TRUE.
*
* @return
- * The full path to the temporary directory where update file archives
- * should be extracted.
+ * The full path to the temporary directory where update file archives should
+ * be extracted.
*/
function _update_manager_extract_directory($create = TRUE) {
$directory = &drupal_static(__FUNCTION__, '');
@@ -898,14 +922,15 @@ function _update_manager_extract_directory($create = TRUE) {
}
/**
- * Return the directory where update archive files should be cached.
+ * Returns the directory where update archive files should be cached.
*
* @param $create
- * If TRUE, attempt to create the directory if it does not already exist.
+ * (optional) Whether to attempt to create the directory if it does not
+ * already exist. Defaults to TRUE.
*
* @return
- * The full path to the temporary directory where update file archives
- * should be cached.
+ * The full path to the temporary directory where update file archives should
+ * be cached.
*/
function _update_manager_cache_directory($create = TRUE) {
$directory = &drupal_static(__FUNCTION__, '');
@@ -919,7 +944,7 @@ function _update_manager_cache_directory($create = TRUE) {
}
/**
- * Clear the temporary files and directories based on file age from disk.
+ * Clears the temporary files and directories based on file age from disk.
*/
function update_clear_update_disk_cache() {
// List of update module cache directories. Do not create the directories if
@@ -936,19 +961,19 @@ function update_clear_update_disk_cache() {
}
/**
- * Delete stale files and directories from the Update manager disk cache.
+ * Deletes stale files and directories from the update manager disk cache.
*
- * Files and directories older than 6 hours and development snapshots older
- * than 5 minutes are considered stale. We only cache development snapshots
- * for 5 minutes since otherwise updated snapshots might not be downloaded as
+ * Files and directories older than 6 hours and development snapshots older than
+ * 5 minutes are considered stale. We only cache development snapshots for 5
+ * minutes since otherwise updated snapshots might not be downloaded as
* expected.
*
* When checking file ages, we need to use the ctime, not the mtime
- * (modification time) since many (all?) tar implementations go out of their
- * way to set the mtime on the files they create to the timestamps recorded
- * in the tarball. We want to see the last time the file was changed on disk,
- * which is left alone by tar and correctly set to the time the archive file
- * was unpacked.
+ * (modification time) since many (all?) tar implementations go out of their way
+ * to set the mtime on the files they create to the timestamps recorded in the
+ * tarball. We want to see the last time the file was changed on disk, which is
+ * left alone by tar and correctly set to the time the archive file was
+ * unpacked.
*
* @param $path
* A string containing a file path or (streamwrapper) URI.
diff --git a/core/modules/update/update.report.inc b/core/modules/update/update.report.inc
index 7703503a770c..0e0cd36d9d19 100644
--- a/core/modules/update/update.report.inc
+++ b/core/modules/update/update.report.inc
@@ -6,7 +6,9 @@
*/
/**
- * Menu callback. Generate a page about the update status of projects.
+ * Page callback: Generates a page about the update status of projects.
+ *
+ * @see update_menu()
*/
function update_status() {
if ($available = update_get_available(TRUE)) {
@@ -257,6 +259,7 @@ function theme_update_report($variables) {
* - status: The integer code for a project's current update status.
*
* @see update_calculate_project_data()
+ * @ingroup themeable
*/
function theme_update_status_label($variables) {
switch ($variables['status']) {
diff --git a/core/modules/update/update.settings.inc b/core/modules/update/update.settings.inc
index 60ac3ca8e4e7..5cd2414987c9 100644
--- a/core/modules/update/update.settings.inc
+++ b/core/modules/update/update.settings.inc
@@ -6,7 +6,11 @@
*/
/**
- * Form builder for the update settings tab.
+ * Form constructor for the update settings form.
+ *
+ * @see update_settings_validate()
+ * @see update_settings_submit()
+ * @ingroup forms
*/
function update_settings($form) {
$form['update_check_frequency'] = array(
@@ -57,9 +61,11 @@ function update_settings($form) {
}
/**
- * Validation callback for the settings form.
+ * Form validation handler for update_settings().
+ *
+ * Validates the e-mail addresses and ensures the field is formatted correctly.
*
- * Validates the email addresses and ensures the field is formatted correctly.
+ * @see update_settings_submit()
*/
function update_settings_validate($form, &$form_state) {
if (!empty($form_state['values']['update_notify_emails'])) {
@@ -89,13 +95,15 @@ function update_settings_validate($form, &$form_state) {
}
/**
- * Submit handler for the settings tab.
+ * Form submission handler for update_settings().
+ *
+ * Also invalidates the cache of available updates if the "Check for updates of
+ * disabled modules and themes" setting is being changed. The available updates
+ * report needs to refetch available update data after this setting changes or
+ * it would show misleading things (e.g., listing the disabled projects on the
+ * site with the "No available releases found" warning).
*
- * Also invalidates the cache of available updates if the "Check for updates
- * of disabled modules and themes" setting is being changed. The available
- * updates report need to refetch available update data after this setting
- * changes or it would show misleading things (e.g. listing the disabled
- * projects on the site with the "No available releases found" warning).
+ * @see update_settings_validate()
*/
function update_settings_submit($form, $form_state) {
$op = $form_state['values']['op'];
--
GitLab