Issue #1606946 by Albert Volkman, udaksh, bunthorne: Fix up API docs for top-level PHP files

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:
@@ -21,16 +21,17 @@
  */
 
 /**
- * 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).
  */
 define('MAINTENANCE_MODE', 'update');
 
@@ -51,7 +52,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');

install.php

@@ -6,12 +6,16 @@
  */
 
 /**
- * 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.
+ *
+ * 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');
 

update.php

 <?php
 
 /**
- * Root directory of Drupal installation.
+ * Defines the root directory of the Drupal installation.
  */
 define('DRUPAL_ROOT', getcwd());
 
@@ -27,6 +27,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');
@@ -37,6 +40,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;
@@ -141,6 +147,9 @@ function update_script_selection_form($form, &$form_state) {
   return $form;
 }
 
+/**
+ * Provides links to the homepage and administration pages.
+ */
 function update_helpful_links() {
   // NOTE: we can't use l() here because the URL would point to
   // 'update.php?q=admin'.
@@ -151,6 +160,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');
   $links = update_helpful_links();
@@ -231,6 +243,15 @@ function update_results_page() {
   return $output;
 }
 
+/**
+ * Provides an overview of the Drupal database update.
+ *
+ * This page provides cautionary suggestions that should happen before
+ * proceeding with the update to ensure data integrity.
+ *
+ * @return
+ *   Rendered HTML form.
+ */
 function update_info_page() {
   // Change query-strings on css/js files to enforce reload for all users.
   _drupal_flush_css_js();
@@ -256,6 +277,12 @@ function update_info_page() {
   return $output;
 }
 
+/**
+ * Renders a 403 access denied page for update.php.
+ *
+ * @return
+ *   Rendered HTML warning with 403 status.
+ */
 function update_access_denied_page() {
   drupal_add_http_header('Status', '403 Forbidden');
   watchdog('access denied', 'update.php', NULL, WATCHDOG_WARNING);
@@ -294,7 +321,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.
@@ -310,8 +337,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();
@@ -322,7 +348,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