diff -u b/core/modules/update/update.authorize.inc b/core/modules/update/update.authorize.inc --- b/core/modules/update/update.authorize.inc +++ b/core/modules/update/update.authorize.inc @@ -181,8 +181,8 @@ * 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 bool $success - * TRUE if the batch operation was successful, FALSE if there were errors. + * @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. */ @@ -248,8 +248,8 @@ * authorize.php will render a report. Also responsible for putting the site * back online after a successful install if necessary. * - * @param bool $success - * TRUE if the batch operation was a success, FALSE if there were errors. + * @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. */ diff -u b/core/modules/update/update.compare.inc b/core/modules/update/update.compare.inc --- b/core/modules/update/update.compare.inc +++ b/core/modules/update/update.compare.inc @@ -18,14 +18,35 @@ * 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 + * 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 array of currently enabled projects. + * 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: TRUE if the project is enabled; FALSE otherwise. + * - 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() @@ -62,7 +83,7 @@ * 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 + * 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 @@ -214,12 +235,12 @@ } /** - * Figures out what project a given file object belongs to. + * Determines what project a given file object belongs to. * * @param $file * A file object as returned by system_get_files_database(). * - * @return string + * @return * The canonical project short name. * * @see system_get_files_database() @@ -236,7 +257,7 @@ } /** - * Figures out version and type information for currently installed projects. + * 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 @@ -303,7 +324,7 @@ * Data about available project releases. * * @return - * An array of installed projects with updated update status information. + * An array of installed projects with current update status information. * * @see update_get_available() * @see update_get_projects() @@ -356,14 +377,14 @@ * 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 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: + * Given a target major version, the available releases is scanned looking for + * the specific release to recommend (avoiding beta releases and development + * snapshots if possible). For the target major version, it finds the highest + * patch level. 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 @@ -396,7 +417,7 @@ * * @param $project_data * An array containing information about a specific project. - * @param array $available + * @param $available * Data about available project releases of a specific project. */ function update_calculate_project_update_status(&$project_data, $available) { diff -u b/core/modules/update/update.fetch.inc b/core/modules/update/update.fetch.inc --- b/core/modules/update/update.fetch.inc +++ b/core/modules/update/update.fetch.inc @@ -31,7 +31,7 @@ /** * Batch callback: Processes a step in batch for fetching available update data. * - * @param array $context + * @param $context * Reference to an array used for Batch API storage. */ function update_fetch_data_batch(&$context) { @@ -80,7 +80,7 @@ * Batch callback: Performs actions when all fetch tasks have been completed. * * @param $success - * TRUE if the batch operation was successful, FALSE if there were errors. + * TRUE if the batch operation was successful; FALSE if there were errors. * @param $results * An associative array of results from the batch operation, including the key * 'updated' which holds the total number of projects we fetched available @@ -267,7 +267,7 @@ * @param $site_key * (optional) The anonymous site key hash. Defaults to an empty string. * - * @return string + * @return * The URL for fetching information about updates to the specified project. * * @see update_fetch_data() @@ -313,8 +313,8 @@ /** * 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 e-mail 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() diff -u b/core/modules/update/update.install b/core/modules/update/update.install --- b/core/modules/update/update.install +++ b/core/modules/update/update.install @@ -2,7 +2,7 @@ /** * @file - * Install, update and uninstall functions for the Update Manager module. + * Install, update, and uninstall functions for the Update Manager module. */ /** diff -u b/core/modules/update/update.manager.inc b/core/modules/update/update.manager.inc --- b/core/modules/update/update.manager.inc +++ b/core/modules/update/update.manager.inc @@ -12,8 +12,8 @@ * 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 + * 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. * @@ -48,14 +48,14 @@ */ /** - * Form constructor for the update manager update form. + * Form constructor for the Update Manager update form. * * This presents a table with all projects that have available updates with * checkboxes to select which ones to upgrade. * * @param $context - * String representing the context from which we're trying to update, can be: - * 'module', 'theme' or 'report'. + * 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() @@ -340,7 +340,7 @@ /** * Batch callback: Performs actions when the download batch is completed. * - * @param bool $success + * @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. @@ -482,14 +482,14 @@ */ /** - * Form constructor for the update manager install form. + * Form constructor for the Update Manager install form. * * This presents a place to enter a URL or upload an archive file to use to * install a new module or theme. * * @param $context - * String representing the context from which we're trying to install, can be: - * 'module', 'theme' or 'report'. + * 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() @@ -750,7 +750,7 @@ * @{ * Update manager file management functions. * - * These functions are used by the update manager to copy, extract and verify + * These functions are used by the update manager to copy, extract, and verify * archive files. */ @@ -765,4 +765,6 @@ * @return Archiver * The Archiver object used to extract the archive. + * + * @throws Exception on failure. */ function update_manager_archive_extract($file, $directory) { @@ -814,7 +816,7 @@ /** * Copies a file from $url to the temporary directory for updates. * - * If the file has already been downloaded, it returns the local path. + * Returns the local path if the file has already been downloaded. * * @param $url * The URL of the file on the server. diff -u b/core/modules/update/update.module b/core/modules/update/update.module --- b/core/modules/update/update.module +++ b/core/modules/update/update.module @@ -441,9 +441,8 @@ * Creates a new fetch task after loading the necessary include file. * * @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. + * Associative array of information about a project. See update_get_projects() + * for the keys used. * * @see _update_create_fetch_task() */ @@ -900,8 +899,8 @@ * Returns the directory where update archive files should be extracted. * * @param $create - * (optional) If TRUE, attempt to create the directory if it does not already - * exist. Defaults to TRUE. + * (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 @@ -922,8 +921,8 @@ * Returns the directory where update archive files should be cached. * * @param $create - * (optional) If TRUE, attempt to create the directory if it does not already - * exist. Defaults to TRUE. + * (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 diff -u b/core/modules/update/update.test b/core/modules/update/update.test --- b/core/modules/update/update.test +++ b/core/modules/update/update.test @@ -171,7 +171,7 @@ } /** - * Checks 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(); @@ -188,7 +188,7 @@ } /** - * Checks 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(); @@ -223,7 +223,7 @@ } /** - * Tests the update module when the update server returns 503 errors. + * Tests the Update Manager module when the update server returns 503 errors. */ function testServiceUnavailable() { $this->refreshUpdateStatus(array(), '503-error'); @@ -233,7 +233,7 @@ } /** - * Resets to 7.0 the version used when no project-specific mapping is defined. + * Sets the version to 7.0 when no project-specific mapping is defined. */ protected function setSystemInfo7_0() { $setting = array( @@ -326,9 +326,9 @@ * * 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" + * 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