From 3448103e03e77cccb47a86250c6f0494708ae8ca Mon Sep 17 00:00:00 2001
From: Jennifer Hodgdon <yahgrp@poplarware.com>
Date: Fri, 14 Sep 2012 08:19:14 -0700
Subject: [PATCH] Issue #1606946 by Albert Volkman, bunthorne: API docs cleanup
for PHP files in core directory
---
core/authorize.php | 35 ++++++++++++++++++-----------------
core/install.php | 10 +++++-----
core/update.php | 24 +++++++++++++++++-------
3 files changed, 40 insertions(+), 29 deletions(-)
diff --git a/core/authorize.php b/core/authorize.php
index 08a344ad083f..a439975cd2be 100644
--- a/core/authorize.php
+++ b/core/authorize.php
@@ -4,16 +4,16 @@
* @file
* Administrative script for running authorized file operations.
*
- * Using this script, the site owner (the user actually owning the files on
- * the webserver) can authorize certain file-related operations to proceed
- * with elevated privileges, for example to deploy and upgrade modules or
- * themes. Users should not visit this page directly, but instead use an
- * administrative user interface which knows how to redirect the user to this
- * script as part of a multistep process. This script actually performs the
- * selected operations without loading all of Drupal, to be able to more
- * gracefully recover from errors. Access to the script is controlled by a
- * global killswitch in settings.php ('allow_authorize_operations') and via
- * the 'administer software updates' permission.
+ * Using this script, the site owner (the user actually owning the files on the
+ * webserver) can authorize certain file-related operations to proceed with
+ * elevated privileges, for example to deploy and upgrade modules or themes.
+ * Users should not visit this page directly, but instead use an administrative
+ * user interface which knows how to redirect the user to this script as part of
+ * a multistep process. This script actually performs the selected operations
+ * without loading all of Drupal, to be able to more gracefully recover from
+ * errors. Access to the script is controlled by a global killswitch in
+ * settings.php ('allow_authorize_operations') and via the 'administer software
+ * updates' permission.
*
* There are helper functions for setting up an operation to run via this
* system in modules/system/system.module. For more information, see:
@@ -24,16 +24,17 @@
chdir('..');
/**
- * Root directory of Drupal installation.
+ * Defines the root directory of the Drupal installation.
*/
define('DRUPAL_ROOT', getcwd());
/**
- * Global flag to identify update.php and authorize.php runs, and so
- * avoid various unwanted operations, such as hook_init() and
- * hook_exit() invokes, css/js preprocessing and translation, and
- * solve some theming issues. This flag is checked on several places
- * in Drupal code (not just authorize.php).
+ * Global flag to identify update.php and authorize.php runs.
+ *
+ * Identifies update.php and authorize.php runs, avoiding unwanted operations
+ * such as hook_init() and hook_exit() invokes, css/js preprocessing and
+ * translation, and solves some theming issues. The flag is checked in other
+ * places in Drupal code (not just authorize.php).
*/
const MAINTENANCE_MODE = 'update';
@@ -54,7 +55,7 @@ function authorize_access_denied_page() {
* have access to the 'administer software updates' permission.
*
* @return
- * TRUE if the current user can run authorize.php, otherwise FALSE.
+ * TRUE if the current user can run authorize.php, and FALSE if not.
*/
function authorize_access_allowed() {
return variable_get('allow_authorize_operations', TRUE) && user_access('administer software updates');
diff --git a/core/install.php b/core/install.php
index 3ea85ff8500a..6f046b21e3da 100644
--- a/core/install.php
+++ b/core/install.php
@@ -9,16 +9,16 @@
chdir('..');
/**
- * Root directory of Drupal installation.
+ * Defines the root directory of the Drupal installation.
*/
define('DRUPAL_ROOT', getcwd());
/**
- * Global flag to indicate that site is in installation mode.
+ * Global flag to indicate the site is in installation mode.
*
- * This constant is defined using define() instead of const so that PHP
- * versions older than 5.3 can display the proper PHP requirements instead of
- * causing a fatal error.
+ * The constant is defined using define() instead of const so that PHP
+ * versions prior to 5.3 can display proper PHP requirements instead of causing
+ * a fatal error.
*/
define('MAINTENANCE_MODE', 'install');
diff --git a/core/update.php b/core/update.php
index b8a726d6a880..52cf3d01a992 100644
--- a/core/update.php
+++ b/core/update.php
@@ -21,11 +21,11 @@
chdir('..');
/**
- * Root directory of Drupal installation.
+ * Defines the root directory of the Drupal installation.
*/
define('DRUPAL_ROOT', getcwd());
-// Exit early if running an incompatible PHP version to avoid fatal errors.
+// Exit early if an incompatible PHP version would cause fatal errors.
// The minimum version is specified explicitly, as DRUPAL_MINIMUM_PHP is not
// yet available. It is defined in bootstrap.inc, but it is not possible to
// load that file yet as it would cause a fatal error on older versions of PHP.
@@ -46,6 +46,9 @@
*/
define('MAINTENANCE_MODE', 'update');
+/**
+ * Renders form with a list of available database updates.
+ */
function update_selection_page() {
drupal_set_title('Drupal database update');
$elements = drupal_get_form('update_script_selection_form');
@@ -56,6 +59,9 @@ function update_selection_page() {
return $output;
}
+/**
+ * Form constructor for the list of available database module updates.
+ */
function update_script_selection_form($form, &$form_state) {
$count = 0;
$incompatible_count = 0;
@@ -157,6 +163,9 @@ function update_script_selection_form($form, &$form_state) {
return $form;
}
+/**
+ * Provides links to the homepage and administration pages.
+ */
function update_helpful_links() {
$links['front'] = array(
'title' => t('Front page'),
@@ -171,6 +180,9 @@ function update_helpful_links() {
return $links;
}
+/**
+ * Displays results of the update script with any accompanying errors.
+ */
function update_results_page() {
drupal_set_title('Drupal database update');
@@ -313,7 +325,7 @@ function update_access_allowed() {
}
/**
- * Add the update task list to the current page.
+ * Adds the update task list to the current page.
*/
function update_task_list($active = NULL) {
// Default list of tasks.
@@ -329,8 +341,7 @@ function update_task_list($active = NULL) {
}
/**
- * Returns (and optionally stores) extra requirements that only apply during
- * particular parts of the update.php process.
+ * Returns and stores extra requirements that apply during the update process.
*/
function update_extra_requirements($requirements = NULL) {
static $extra_requirements = array();
@@ -341,7 +352,7 @@ function update_extra_requirements($requirements = NULL) {
}
/**
- * Check update requirements and report any errors or (optionally) warnings.
+ * Checks update requirements and reports errors and (optionally) warnings.
*
* @param $skip_warnings
* (optional) If set to TRUE, requirement warnings will be ignored, and a
@@ -507,5 +518,4 @@ function update_check_requirements($skip_warnings = FALSE) {
else {
print theme('update_page', array('content' => $output, 'show_messages' => !$progress_page));
}
-
}
--
GitLab