Ticket #25442: 25442.2.diff

src/wp-admin/admin.php

@@ -36 +36 @@
         update_option( 'db_upgraded',  false );
 
         /**
-         * Runs on the next page load after successful upgrade
+         * Fires on the next page load after successful upgrade.
          *
-         * @since 2.8
+         * @since 2.8.0
          */
-        do_action('after_db_upgrade');
+        do_action( 'after_db_upgrade' );
 } elseif ( get_option('db_version') != $wp_db_version && empty($_POST) ) {
         if ( !is_multisite() ) {
                 wp_redirect( admin_url( 'upgrade.php?_wp_http_referer=' . urlencode( wp_unslash( $_SERVER['REQUEST_URI'] ) ) ) );
                 exit;
+        /**
+         * Filter whether to perform the Multisite upgrade routine.
+         *
+         * @since 3.0.0
+         *
+         * @param bool true Whether to perform the Multisite upgrade routine. Default true.
+         */
         } elseif ( apply_filters( 'do_mu_upgrade', true ) ) {
                 /**
                  * On really small MU installs run the upgrader every time,
@@ -57 +64 @@
                 if ( $c <= 50 || ( $c > 50 && mt_rand( 0, (int)( $c / 50 ) ) == 1 ) ) {
                         require_once( ABSPATH . WPINC . '/http.php' );
                         $response = wp_remote_get( admin_url( 'upgrade.php?step=1' ), array( 'timeout' => 120, 'httpversion' => '1.1' ) );
+                        /**
+                         * Fires after the Multisite upgrade is complete.
+                         *
+                         * @since 3.0.0
+                         *
+                         * @param array|WP_Error $response The upgrade response array or WP_Error on failure.
+                         */
                         do_action( 'after_mu_upgrade', $response );
                         unset($response);
                 }
@@ -103 +117 @@
 else
         require(ABSPATH . 'wp-admin/menu.php');
 
-if ( current_user_can( 'manage_options' ) )
+if ( current_user_can( 'manage_options' ) ) {
+        /**
+         * Filter the maximum memory limit available for administration screens.
+         *
+         * The WP_MAX_MEMORY_LIMIT constant specifically defines the maximum memory limit available
+         * when in the administration back-end. The default is 256M, or 256 megabytes of memory.
+         *
+         * @since 3.0.0
+         *
+         * @param string 'WP_MAX_MEMORY_LIMIT' The maximum WordPress memory limit. Default 256M.
+         */
         @ini_set( 'memory_limit', apply_filters( 'admin_memory_limit', WP_MAX_MEMORY_LIMIT ) );
+}
 
-do_action('admin_init');
+/**
+ * Fires at the beginning of any admin page, before the page is rendered.
+ *
+ * @since 2.5.0
+ */
+do_action( 'admin_init' );
 
 if ( isset($plugin_page) ) {
         if ( !empty($typenow) )
@@ -142 +172 @@
 // Handle plugin admin pages.
 if ( isset($plugin_page) ) {
         if ( $page_hook ) {
-                do_action('load-' . $page_hook);
+                /**
+                 * Fires before a plugin page is loaded where $page_hook is not empty.
+                 *
+                 * The dynamic portion of the hook name, $page_hook, refers to a mixture of plugin
+                 * page information including:
+                 * 1. The page type. If the plugin page is registered as a submenu page, such as for
+                 *    Settings, the page type would be 'settings'. Otherwise the type is 'toplevel'.
+                 * 2. A separator of '_page_'.
+                 * 3. The plugin basename minus the file extension.
+                 *
+                 * Together, the three parts form the $page_hook. Citing the example above,
+                 * the hook name used would be 'load-settings_page_pluginbasename'.
+                 *
+                 * @see get_plugin_page_hook()
+                 *
+                 * @since 2.1.0
+                 */
+                do_action( 'load-' . $page_hook );
                 if (! isset($_GET['noheader']))
                         require_once(ABSPATH . 'wp-admin/admin-header.php');
 
-                do_action($page_hook);
+                /**
+                 * Fires after the admin header is loaded for a plugin page where $page_hook is not empty.
+                 *
+                 * The dynamic hook name, $page_hook, refers to a mixture of plugin page information including:
+                 * 1. The page type. If the plugin page is registered as a submenu page, such as for Settings,
+                 *    the page type would be 'settings'. Otherwise the type is 'toplevel'.
+                 * 2. A separator of '_page_'.
+                 * 3. The plugin basename minus the file extension.
+                 *
+                 * Together, the three parts form the $page_hook. Citing the example above,
+                 * the hook name used would be 'load-settings_page_pluginbasename'.
+                 *
+                 * @since 1.5.0
+                 */
+                do_action( $page_hook );
         } else {
                 if ( validate_file($plugin_page) )
                         wp_die(__('Invalid plugin page'));
@@ -154 +215 @@
                 if ( !( file_exists(WP_PLUGIN_DIR . "/$plugin_page") && is_file(WP_PLUGIN_DIR . "/$plugin_page") ) && !( file_exists(WPMU_PLUGIN_DIR . "/$plugin_page") && is_file(WPMU_PLUGIN_DIR . "/$plugin_page") ) )
                         wp_die(sprintf(__('Cannot load %s.'), htmlentities($plugin_page)));
 
-                do_action('load-' . $plugin_page);
+                /**
+                 * Fires before a plugin page is loaded where $page_hook is empty.
+                 *
+                 * The dynamic portion of the hook name, $plugin_page, refers to the plugin basename.
+                 *
+                 * @see plugin_basename()
+                 *
+                 * @since 1.5.0
+                 */
+                do_action( 'load-' . $plugin_page );
 
                 if ( !isset($_GET['noheader']))
                         require_once(ABSPATH . 'wp-admin/admin-header.php');
@@ -185 +255 @@
                 exit;
         }
 
+        /**
+         * Fires before an importer page is loaded.
+         *
+         * The dynamic portion of the hook name, $importer, refers to the importer slug.
+         *
+         * @since 3.5.0
+         */
         do_action( 'load-importer-' . $importer );
 
         $parent_file = 'tools.php';
@@ -198 +275 @@
 
         define('WP_IMPORTING', true);
 
+        /**
+         * Whether to filter imported data through kses on import.
+         *
+         * In Multisite, imported data is filtered through kses by default
+         * by filtering on this hook and returning true.
+         *
+         * @since 3.1.0
+         *
+         * @param bool false Whether to force data to be filtered through kses. Default false.
+         */
         if ( apply_filters( 'force_filtered_html_on_import', false ) )
                 kses_init_filters();  // Always filter imported data with kses on multisite.
 
@@ -210 +297 @@
 
         exit();
 } else {
-        do_action("load-$pagenow");
+        /**
+         * Fires before an admin page is loaded.
+         *
+         * The dynamic portion of the hook name, $pagenow, is a global variable
+         * referring to the filename of the current page, such as 'admin.php',
+         * 'post-new.php' etc. A complete hook for the latter would be 'load-post-new.php'.
+         *
+         * @since 2.1.0
+         */
+        do_action( 'load-' . $pagenow );
         // Backwards compatibility with old load-page-new.php, load-page.php,
         // and load-categories.php actions.
         if ( $typenow == 'page' ) {
@@ -226 +322 @@
         }
 }
 
-if ( !empty($_REQUEST['action']) )
+if ( !empty($_REQUEST['action']) ) {
+        /**
+         * Fires before the page loads for the requested action.
+         *
+         * The dynamic portion of the hook name, $_REQUEST['action'], refers to the action
+         * derived from the $_REQUEST super global passed to admin.php.
+         *
+         * @since 2.6.0
+         */
         do_action('admin_action_' . $_REQUEST['action']);
+}