enmi-conf.org: comparison wp/wp-admin/includes/plugin.php

equal deleted inserted replaced

-:be944660c56a
+:3d72ae0968f4
 * @param bool   $translate   Optional. If the returned data should be translated. Default true.
 * @return array {
 *     Plugin data. Values will be empty if not supplied by the plugin.
 *
 *     @type string $Name        Name of the plugin. Should be unique.
-*     @type string $Title       Title of the plugin and link to the plugin's site (if set).
+*     @type string $PluginURI   Plugin URI.
+*     @type string $Version     Plugin version.
 *     @type string $Description Plugin description.
-*     @type string $Author      Author's name.
+*     @type string $Author      Plugin author's name.
-*     @type string $AuthorURI   Author's website address (if set).
+*     @type string $AuthorURI   Plugin author's website address (if set).
-*     @type string $Version     Plugin version.
 *     @type string $TextDomain  Plugin textdomain.
-*     @type string $DomainPath  Plugins relative directory path to .mo files.
+*     @type string $DomainPath  Plugin's relative directory path to .mo files.
 *     @type bool   $Network     Whether the plugin can only be activated network-wide.
 *     @type string $RequiresWP  Minimum required version of WordPress.
 *     @type string $RequiresPHP Minimum required version of PHP.
 *     @type string $UpdateURI   ID of the plugin for update purposes, should be a URI.
+*     @type string $Title       Title of the plugin and link to the plugin's site (if set).
+*     @type string $AuthorName  Plugin author's name.
 * }
 */
 function get_plugin_data( $plugin_file, $markup = true, $translate = true ) {
 	$default_headers = array(
 * @param string $plugin_file Path to the main plugin file.
 * @param array  $plugin_data An array of plugin data. See `get_plugin_data()`.
 * @param bool   $markup      Optional. If the returned data should have HTML markup applied.
 *                            Default true.
 * @param bool   $translate   Optional. If the returned data should be translated. Default true.
-* @return array {
+* @return array Plugin data. Values will be empty if not supplied by the plugin.
-*     Plugin data. Values will be empty if not supplied by the plugin.
+*               See get_plugin_data() for the list of possible values.
-*
-*     @type string $Name        Name of the plugin. Should be unique.
-*     @type string $Title       Title of the plugin and link to the plugin's site (if set).
-*     @type string $Description Plugin description.
-*     @type string $Author      Author's name.
-*     @type string $AuthorURI   Author's website address (if set).
-*     @type string $Version     Plugin version.
-*     @type string $TextDomain  Plugin textdomain.
-*     @type string $DomainPath  Plugins relative directory path to .mo files.
-*     @type bool   $Network     Whether the plugin can only be activated network-wide.
-* }
 */
 function _get_plugin_data_markup_translate( $plugin_file, $plugin_data, $markup = true, $translate = true ) {
 	// Sanitize the plugin filename to a WP_PLUGIN_DIR relative path.
 	$plugin_file = plugin_basename( $plugin_file );
 		} elseif ( 'hello.php' === basename( $plugin_file ) ) {
 			$textdomain = 'default';
 		}
 		if ( $textdomain ) {
 			foreach ( array( 'Name', 'PluginURI', 'Description', 'Author', 'AuthorURI', 'Version' ) as $field ) {
-				// phpcs:ignore WordPress.WP.I18n.LowLevelTranslationFunction,WordPress.WP.I18n.NonSingularStringLiteralText,WordPress.WP.I18n.NonSingularStringLiteralDomain
+				if ( ! empty( $plugin_data[ $field ] ) ) {
-				$plugin_data[ $field ] = translate( $plugin_data[ $field ], $textdomain );
+					// phpcs:ignore WordPress.WP.I18n.LowLevelTranslationFunction,WordPress.WP.I18n.NonSingularStringLiteralText,WordPress.WP.I18n.NonSingularStringLiteralDomain
+					$plugin_data[ $field ] = translate( $plugin_data[ $field ], $textdomain );
+				}
 			}
 		}
 	}
 	// Sanitize fields.
 	return $plugin_data;
 }
 /**
-* Get a list of a plugin's files.
+* Gets a list of a plugin's files.
 *
 * @since 2.8.0
 *
 * @param string $plugin Path to the plugin file relative to the plugins directory.
 * @return string[] Array of file names relative to the plugin root.
 	return $plugin_files;
 }
 /**
-* Check the plugins directory and retrieve all plugin files with plugin data.
+* Checks the plugins directory and retrieve all plugin files with plugin data.
 *
 * WordPress only supports plugin files in the base plugins directory
 * (wp-content/plugins) and in one directory above the plugins directory
 * (wp-content/plugins/my-plugin). The file it looks for has the plugin data
 * and must be found in those two locations. It is recommended to keep your
 	return $wp_plugins;
 }
 /**
-* Check the mu-plugins directory and retrieve all mu-plugin files with any plugin data.
+* Checks the mu-plugins directory and retrieve all mu-plugin files with any plugin data.
 *
 * WordPress only includes mu-plugin files in the base mu-plugins directory (wp-content/mu-plugins).
 *
 * @since 3.0.0
 * @return array[] Array of arrays of mu-plugin data, keyed by plugin file name. See `get_plugin_data()`.
 	return $wp_plugins;
 }
 /**
-* Callback to sort array by a 'Name' key.
+* Declares a callback to sort array by a 'Name' key.
 *
 * @since 3.1.0
 *
 * @access private
 *
 function _sort_uname_callback( $a, $b ) {
 	return strnatcasecmp( $a['Name'], $b['Name'] );
 }
 /**
-* Check the wp-content directory and retrieve all drop-ins with any plugin data.
+* Checks the wp-content directory and retrieve all drop-ins with any plugin data.
 *
 * @since 3.0.0
 * @return array[] Array of arrays of dropin plugin data, keyed by plugin file name. See `get_plugin_data()`.
 */
 function get_dropins() {
 	return null;
 }
 /**
-* Deactivate a single plugin or multiple plugins.
+* Deactivates a single plugin or multiple plugins.
 *
 * The deactivation hook is disabled by the plugin upgrader by using the $silent
 * parameter.
 *
 * @since 2.5.0
 		update_site_option( 'active_sitewide_plugins', $network_current );
 	}
 }
 /**
-* Activate multiple plugins.
+* Activates multiple plugins.
 *
 * When WP_Error is returned, it does not mean that one of the plugins had
 * errors. It means that one or more of the plugin file paths were invalid.
 *
 * The execution will be halted as soon as one of the plugins has an error.
 	return true;
 }
 /**
-* Remove directory and files of a plugin for a list of plugins.
+* Removes directory and files of a plugin for a list of plugins.
 *
 * @since 2.6.0
 *
 * @global WP_Filesystem_Base $wp_filesystem WordPress filesystem subclass.
 *
 	return true;
 }
 /**
-* Validate active plugins
+* Validates active plugins.
 *
 * Validate all active plugins, deactivates invalid and
 * returns an array of deactivated ones.
 *
 * @since 2.5.0
 	}
 	return $invalid;
 }
 /**
-* Validate the plugin path.
+* Validates the plugin path.
 *
 * Checks that the main plugin file exists and is a valid plugin. See validate_file().
 *
 * @since 2.5.0
 *
 	return true;
 }
 /**
-* Whether the plugin can be uninstalled.
+* Determines whether the plugin can be uninstalled.
 *
 * @since 2.7.0
 *
 * @param string $plugin Path to the plugin file relative to the plugins directory.
 * @return bool Whether plugin can be uninstalled.
 	return false;
 }
 /**
-* Uninstall a single plugin.
+* Uninstalls a single plugin.
 *
 * Calls the uninstall hook, if it is available.
 *
 * @since 2.7.0
 *
 //
 // Menu.
 //
 /**
-* Add a top-level menu page.
+* Adds a top-level menu page.
 *
 * This function takes a capability which will be used to determine whether
 * or not a page is included in the menu.
 *
 * The function which is hooked in to handle the output of the page must check
 * @global array $menu
 * @global array $admin_page_hooks
 * @global array $_registered_pages
 * @global array $_parent_pages
 *
-* @param string   $page_title The text to be displayed in the title tags of the page when the menu is selected.
+* @param string    $page_title The text to be displayed in the title tags of the page when the menu is selected.
-* @param string   $menu_title The text to be used for the menu.
+* @param string    $menu_title The text to be used for the menu.
-* @param string   $capability The capability required for this menu to be displayed to the user.
+* @param string    $capability The capability required for this menu to be displayed to the user.
-* @param string   $menu_slug  The slug name to refer to this menu by. Should be unique for this menu page and only
+* @param string    $menu_slug  The slug name to refer to this menu by. Should be unique for this menu page and only
-*                             include lowercase alphanumeric, dashes, and underscores characters to be compatible
+*                              include lowercase alphanumeric, dashes, and underscores characters to be compatible
-*                             with sanitize_key().
+*                              with sanitize_key().
-* @param callable $function   The function to be called to output the content for this page.
+* @param callable  $callback   Optional. The function to be called to output the content for this page.
-* @param string   $icon_url   The URL to the icon to be used for this menu.
+* @param string    $icon_url   Optional. The URL to the icon to be used for this menu.
-*                             * Pass a base64-encoded SVG using a data URI, which will be colored to match
+*                              * Pass a base64-encoded SVG using a data URI, which will be colored to match
-*                               the color scheme. This should begin with 'data:image/svg+xml;base64,'.
+*                                the color scheme. This should begin with 'data:image/svg+xml;base64,'.
-*                             * Pass the name of a Dashicons helper class to use a font icon,
+*                              * Pass the name of a Dashicons helper class to use a font icon,
-*                               e.g. 'dashicons-chart-pie'.
+*                                e.g. 'dashicons-chart-pie'.
-*                             * Pass 'none' to leave div.wp-menu-image empty so an icon can be added via CSS.
+*                              * Pass 'none' to leave div.wp-menu-image empty so an icon can be added via CSS.
-* @param int      $position   The position in the menu order this item should appear.
+* @param int|float $position   Optional. The position in the menu order this item should appear.
 * @return string The resulting page's hook_suffix.
 */
-function add_menu_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $icon_url = '', $position = null ) {
+function add_menu_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $icon_url = '', $position = null ) {
 	global $menu, $admin_page_hooks, $_registered_pages, $_parent_pages;
 	$menu_slug = plugin_basename( $menu_slug );
 	$admin_page_hooks[ $menu_slug ] = sanitize_title( $menu_title );
 	$hookname = get_plugin_page_hookname( $menu_slug, '' );
-	if ( ! empty( $function ) && ! empty( $hookname ) && current_user_can( $capability ) ) {
+	if ( ! empty( $callback ) && ! empty( $hookname ) && current_user_can( $capability ) ) {
-		add_action( $hookname, $function );
+		add_action( $hookname, $callback );
 	}
 	if ( empty( $icon_url ) ) {
 		$icon_url   = 'dashicons-admin-generic';
 		$icon_class = 'menu-icon-generic ';
 		$icon_class = '';
 	}
 	$new_menu = array( $menu_title, $capability, $menu_slug, $page_title, 'menu-top ' . $icon_class . $hookname, $hookname, $icon_url );
-	if ( null === $position ) {
+	if ( null !== $position && ! is_numeric( $position ) ) {
+		_doing_it_wrong(
+			__FUNCTION__,
+			sprintf(
+				/* translators: %s: add_menu_page() */
+				__( 'The seventh parameter passed to %s should be numeric representing menu position.' ),
+				'<code>add_menu_page()</code>'
+			),
+			'6.0.0'
+		);
+		$position = null;
+	}
+	if ( null === $position || ! is_numeric( $position ) ) {
 		$menu[] = $new_menu;
-	} elseif ( isset( $menu[ "$position" ] ) ) {
+	} elseif ( isset( $menu[ (string) $position ] ) ) {
-		$position            = $position + substr( base_convert( md5( $menu_slug . $menu_title ), 16, 10 ), -5 ) * 0.00001;
+		$collision_avoider = base_convert( substr( md5( $menu_slug . $menu_title ), -4 ), 16, 10 ) * 0.00001;
-		$menu[ "$position" ] = $new_menu;
+		$position          = (string) ( $position + $collision_avoider );
+		$menu[ $position ] = $new_menu;
 	} else {
+		/*
+		 * Cast menu position to a string.
+		 *
+		 * This allows for floats to be passed as the position. PHP will normally cast a float to an
+		 * integer value, this ensures the float retains its mantissa (positive fractional part).
+		 *
+		 * A string containing an integer value, eg "10", is treated as a numeric index.
+		 */
+		$position          = (string) $position;
 		$menu[ $position ] = $new_menu;
 	}
 	$_registered_pages[ $hookname ] = true;
 	return $hookname;
 }
 /**
-* Add a submenu page.
+* Adds a submenu page.
 *
 * This function takes a capability which will be used to determine whether
 * or not a page is included in the menu.
 *
 * The function which is hooked in to handle the output of the page must check
 * @global array $_wp_real_parent_file
 * @global bool  $_wp_submenu_nopriv
 * @global array $_registered_pages
 * @global array $_parent_pages
 *
-* @param string   $parent_slug The slug name for the parent menu (or the file name of a standard
+* @param string    $parent_slug The slug name for the parent menu (or the file name of a standard
-*                              WordPress admin page).
+*                               WordPress admin page).
-* @param string   $page_title  The text to be displayed in the title tags of the page when the menu
+* @param string    $page_title  The text to be displayed in the title tags of the page when the menu
-*                              is selected.
+*                               is selected.
-* @param string   $menu_title  The text to be used for the menu.
+* @param string    $menu_title  The text to be used for the menu.
-* @param string   $capability  The capability required for this menu to be displayed to the user.
+* @param string    $capability  The capability required for this menu to be displayed to the user.
-* @param string   $menu_slug   The slug name to refer to this menu by. Should be unique for this menu
+* @param string    $menu_slug   The slug name to refer to this menu by. Should be unique for this menu
-*                              and only include lowercase alphanumeric, dashes, and underscores characters
+*                               and only include lowercase alphanumeric, dashes, and underscores characters
-*                              to be compatible with sanitize_key().
+*                               to be compatible with sanitize_key().
-* @param callable $function    The function to be called to output the content for this page.
+* @param callable  $callback    Optional. The function to be called to output the content for this page.
-* @param int      $position    The position in the menu order this item should appear.
+* @param int|float $position    Optional. The position in the menu order this item should appear.
 * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
 */
-function add_submenu_page( $parent_slug, $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) {
+function add_submenu_page( $parent_slug, $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
 	global $submenu, $menu, $_wp_real_parent_file, $_wp_submenu_nopriv,
 		$_registered_pages, $_parent_pages;
 	$menu_slug   = plugin_basename( $menu_slug );
 	$parent_slug = plugin_basename( $parent_slug );
 			}
 		}
 	}
 	$new_sub_menu = array( $menu_title, $capability, $menu_slug, $page_title );
-	if ( ! is_int( $position ) ) {
-		if ( null !== $position ) {
+	if ( null !== $position && ! is_numeric( $position ) ) {
-			_doing_it_wrong(
+		_doing_it_wrong(
-				__FUNCTION__,
+			__FUNCTION__,
-				sprintf(
+			sprintf(
-					/* translators: %s: add_submenu_page() */
+				/* translators: %s: add_submenu_page() */
-					__( 'The seventh parameter passed to %s should be an integer representing menu position.' ),
+				__( 'The seventh parameter passed to %s should be numeric representing menu position.' ),
-					'<code>add_submenu_page()</code>'
+				'<code>add_submenu_page()</code>'
-				),
+			),
-				'5.3.0'
+			'5.3.0'
-			);
+		);
-		}
+		$position = null;
+	}
+	if (
+		null === $position ||
+		( ! isset( $submenu[ $parent_slug ] ) || $position >= count( $submenu[ $parent_slug ] ) )
+	) {
 		$submenu[ $parent_slug ][] = $new_sub_menu;
 	} else {
-		// Append the submenu if the parent item is not present in the submenu,
+		// Test for a negative position.
-		// or if position is equal or higher than the number of items in the array.
+		$position = max( $position, 0 );
-		if ( ! isset( $submenu[ $parent_slug ] ) || $position >= count( $submenu[ $parent_slug ] ) ) {
+		if ( 0 === $position ) {
-			$submenu[ $parent_slug ][] = $new_sub_menu;
+			// For negative or `0` positions, prepend the submenu.
+			array_unshift( $submenu[ $parent_slug ], $new_sub_menu );
 		} else {
-			// Test for a negative position.
+			// Grab all of the items before the insertion point.
-			$position = max( $position, 0 );
+			$before_items = array_slice( $submenu[ $parent_slug ], 0, $position, true );
-			if ( 0 === $position ) {
+			// Grab all of the items after the insertion point.
-				// For negative or `0` positions, prepend the submenu.
+			$after_items = array_slice( $submenu[ $parent_slug ], $position, null, true );
-				array_unshift( $submenu[ $parent_slug ], $new_sub_menu );
+			// Add the new item.
-			} else {
+			$before_items[] = $new_sub_menu;
-				// Grab all of the items before the insertion point.
+			// Merge the items.
-				$before_items = array_slice( $submenu[ $parent_slug ], 0, $position, true );
+			$submenu[ $parent_slug ] = array_merge( $before_items, $after_items );
-				// Grab all of the items after the insertion point.
+		}
-				$after_items = array_slice( $submenu[ $parent_slug ], $position, null, true );
+	}
-				// Add the new item.
-				$before_items[] = $new_sub_menu;
-				// Merge the items.
-				$submenu[ $parent_slug ] = array_merge( $before_items, $after_items );
-			}
-		}
-	}
 	// Sort the parent array.
 	ksort( $submenu[ $parent_slug ] );
 	$hookname = get_plugin_page_hookname( $menu_slug, $parent_slug );
-	if ( ! empty( $function ) && ! empty( $hookname ) ) {
+	if ( ! empty( $callback ) && ! empty( $hookname ) ) {
-		add_action( $hookname, $function );
+		add_action( $hookname, $callback );
 	}
 	$_registered_pages[ $hookname ] = true;
 	/*
 	return $hookname;
 }
 /**
-* Add submenu page to the Tools main menu.
+* Adds a submenu page to the Tools main menu.
 *
 * This function takes a capability which will be used to determine whether
 * or not a page is included in the menu.
 *
 * The function which is hooked in to handle the output of the page must check
 *
 * @param string   $page_title The text to be displayed in the title tags of the page when the menu is selected.
 * @param string   $menu_title The text to be used for the menu.
 * @param string   $capability The capability required for this menu to be displayed to the user.
 * @param string   $menu_slug  The slug name to refer to this menu by (should be unique for this menu).
-* @param callable $function   The function to be called to output the content for this page.
+* @param callable $callback   Optional. The function to be called to output the content for this page.
-* @param int      $position   The position in the menu order this item should appear.
+* @param int      $position   Optional. The position in the menu order this item should appear.
 * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
 */
-function add_management_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) {
+function add_management_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
-	return add_submenu_page( 'tools.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position );
+	return add_submenu_page( 'tools.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
 }
 /**
-* Add submenu page to the Settings main menu.
+* Adds a submenu page to the Settings main menu.
 *
 * This function takes a capability which will be used to determine whether
 * or not a page is included in the menu.
 *
 * The function which is hooked in to handle the output of the page must check
 *
 * @param string   $page_title The text to be displayed in the title tags of the page when the menu is selected.
 * @param string   $menu_title The text to be used for the menu.
 * @param string   $capability The capability required for this menu to be displayed to the user.
 * @param string   $menu_slug  The slug name to refer to this menu by (should be unique for this menu).
-* @param callable $function   The function to be called to output the content for this page.
+* @param callable $callback   Optional. The function to be called to output the content for this page.
-* @param int      $position   The position in the menu order this item should appear.
+* @param int      $position   Optional. The position in the menu order this item should appear.
 * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
 */
-function add_options_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) {
+function add_options_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
-	return add_submenu_page( 'options-general.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position );
+	return add_submenu_page( 'options-general.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
 }
 /**
-* Add submenu page to the Appearance main menu.
+* Adds a submenu page to the Appearance main menu.
 *
 * This function takes a capability which will be used to determine whether
 * or not a page is included in the menu.
 *
 * The function which is hooked in to handle the output of the page must check
 *
 * @param string   $page_title The text to be displayed in the title tags of the page when the menu is selected.
 * @param string   $menu_title The text to be used for the menu.
 * @param string   $capability The capability required for this menu to be displayed to the user.
 * @param string   $menu_slug  The slug name to refer to this menu by (should be unique for this menu).
-* @param callable $function   The function to be called to output the content for this page.
+* @param callable $callback   Optional. The function to be called to output the content for this page.
-* @param int      $position   The position in the menu order this item should appear.
+* @param int      $position   Optional. The position in the menu order this item should appear.
 * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
 */
-function add_theme_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) {
+function add_theme_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
-	return add_submenu_page( 'themes.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position );
+	return add_submenu_page( 'themes.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
 }
 /**
-* Add submenu page to the Plugins main menu.
+* Adds a submenu page to the Plugins main menu.
 *
 * This function takes a capability which will be used to determine whether
 * or not a page is included in the menu.
 *
 * The function which is hooked in to handle the output of the page must check
 *
 * @param string   $page_title The text to be displayed in the title tags of the page when the menu is selected.
 * @param string   $menu_title The text to be used for the menu.
 * @param string   $capability The capability required for this menu to be displayed to the user.
 * @param string   $menu_slug  The slug name to refer to this menu by (should be unique for this menu).
-* @param callable $function   The function to be called to output the content for this page.
+* @param callable $callback   Optional. The function to be called to output the content for this page.
-* @param int      $position   The position in the menu order this item should appear.
+* @param int      $position   Optional. The position in the menu order this item should appear.
 * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
 */
-function add_plugins_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) {
+function add_plugins_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
-	return add_submenu_page( 'plugins.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position );
+	return add_submenu_page( 'plugins.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
 }
 /**
-* Add submenu page to the Users/Profile main menu.
+* Adds a submenu page to the Users/Profile main menu.
 *
 * This function takes a capability which will be used to determine whether
 * or not a page is included in the menu.
 *
 * The function which is hooked in to handle the output of the page must check
 *
 * @param string   $page_title The text to be displayed in the title tags of the page when the menu is selected.
 * @param string   $menu_title The text to be used for the menu.
 * @param string   $capability The capability required for this menu to be displayed to the user.
 * @param string   $menu_slug  The slug name to refer to this menu by (should be unique for this menu).
-* @param callable $function   The function to be called to output the content for this page.
+* @param callable $callback   Optional. The function to be called to output the content for this page.
-* @param int      $position   The position in the menu order this item should appear.
+* @param int      $position   Optional. The position in the menu order this item should appear.
 * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
 */
-function add_users_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) {
+function add_users_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
 	if ( current_user_can( 'edit_users' ) ) {
 		$parent = 'users.php';
 	} else {
 		$parent = 'profile.php';
 	}
-	return add_submenu_page( $parent, $page_title, $menu_title, $capability, $menu_slug, $function, $position );
+	return add_submenu_page( $parent, $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
 }
 /**
-* Add submenu page to the Dashboard main menu.
+* Adds a submenu page to the Dashboard main menu.
 *
 * This function takes a capability which will be used to determine whether
 * or not a page is included in the menu.
 *
 * The function which is hooked in to handle the output of the page must check
 *
 * @param string   $page_title The text to be displayed in the title tags of the page when the menu is selected.
 * @param string   $menu_title The text to be used for the menu.
 * @param string   $capability The capability required for this menu to be displayed to the user.
 * @param string   $menu_slug  The slug name to refer to this menu by (should be unique for this menu).
-* @param callable $function   The function to be called to output the content for this page.
+* @param callable $callback   Optional. The function to be called to output the content for this page.
-* @param int      $position   The position in the menu order this item should appear.
+* @param int      $position   Optional. The position in the menu order this item should appear.
 * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
 */
-function add_dashboard_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) {
+function add_dashboard_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
-	return add_submenu_page( 'index.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position );
+	return add_submenu_page( 'index.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
 }
 /**
-* Add submenu page to the Posts main menu.
+* Adds a submenu page to the Posts main menu.
 *
 * This function takes a capability which will be used to determine whether
 * or not a page is included in the menu.
 *
 * The function which is hooked in to handle the output of the page must check
 *
 * @param string   $page_title The text to be displayed in the title tags of the page when the menu is selected.
 * @param string   $menu_title The text to be used for the menu.
 * @param string   $capability The capability required for this menu to be displayed to the user.
 * @param string   $menu_slug  The slug name to refer to this menu by (should be unique for this menu).
-* @param callable $function   The function to be called to output the content for this page.
+* @param callable $callback   Optional. The function to be called to output the content for this page.
-* @param int      $position   The position in the menu order this item should appear.
+* @param int      $position   Optional. The position in the menu order this item should appear.
 * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
 */
-function add_posts_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) {
+function add_posts_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
-	return add_submenu_page( 'edit.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position );
+	return add_submenu_page( 'edit.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
 }
 /**
-* Add submenu page to the Media main menu.
+* Adds a submenu page to the Media main menu.
 *
 * This function takes a capability which will be used to determine whether
 * or not a page is included in the menu.
 *
 * The function which is hooked in to handle the output of the page must check
 *
 * @param string   $page_title The text to be displayed in the title tags of the page when the menu is selected.
 * @param string   $menu_title The text to be used for the menu.
 * @param string   $capability The capability required for this menu to be displayed to the user.
 * @param string   $menu_slug  The slug name to refer to this menu by (should be unique for this menu).
-* @param callable $function   The function to be called to output the content for this page.
+* @param callable $callback   Optional. The function to be called to output the content for this page.
-* @param int      $position   The position in the menu order this item should appear.
+* @param int      $position   Optional. The position in the menu order this item should appear.
 * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
 */
-function add_media_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) {
+function add_media_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
-	return add_submenu_page( 'upload.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position );
+	return add_submenu_page( 'upload.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
 }
 /**
-* Add submenu page to the Links main menu.
+* Adds a submenu page to the Links main menu.
 *
 * This function takes a capability which will be used to determine whether
 * or not a page is included in the menu.
 *
 * The function which is hooked in to handle the output of the page must check
 *
 * @param string   $page_title The text to be displayed in the title tags of the page when the menu is selected.
 * @param string   $menu_title The text to be used for the menu.
 * @param string   $capability The capability required for this menu to be displayed to the user.
 * @param string   $menu_slug  The slug name to refer to this menu by (should be unique for this menu).
-* @param callable $function   The function to be called to output the content for this page.
+* @param callable $callback   Optional. The function to be called to output the content for this page.
-* @param int      $position   The position in the menu order this item should appear.
+* @param int      $position   Optional. The position in the menu order this item should appear.
 * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
 */
-function add_links_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) {
+function add_links_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
-	return add_submenu_page( 'link-manager.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position );
+	return add_submenu_page( 'link-manager.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
 }
 /**
-* Add submenu page to the Pages main menu.
+* Adds a submenu page to the Pages main menu.
 *
 * This function takes a capability which will be used to determine whether
 * or not a page is included in the menu.
 *
 * The function which is hooked in to handle the output of the page must check
 *
 * @param string   $page_title The text to be displayed in the title tags of the page when the menu is selected.
 * @param string   $menu_title The text to be used for the menu.
 * @param string   $capability The capability required for this menu to be displayed to the user.
 * @param string   $menu_slug  The slug name to refer to this menu by (should be unique for this menu).
-* @param callable $function   The function to be called to output the content for this page.
+* @param callable $callback   Optional. The function to be called to output the content for this page.
-* @param int      $position   The position in the menu order this item should appear.
+* @param int      $position   Optional. The position in the menu order this item should appear.
 * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
 */
-function add_pages_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) {
+function add_pages_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
-	return add_submenu_page( 'edit.php?post_type=page', $page_title, $menu_title, $capability, $menu_slug, $function, $position );
+	return add_submenu_page( 'edit.php?post_type=page', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
 }
 /**
-* Add submenu page to the Comments main menu.
+* Adds a submenu page to the Comments main menu.
 *
 * This function takes a capability which will be used to determine whether
 * or not a page is included in the menu.
 *
 * The function which is hooked in to handle the output of the page must check
 *
 * @param string   $page_title The text to be displayed in the title tags of the page when the menu is selected.
 * @param string   $menu_title The text to be used for the menu.
 * @param string   $capability The capability required for this menu to be displayed to the user.
 * @param string   $menu_slug  The slug name to refer to this menu by (should be unique for this menu).
-* @param callable $function   The function to be called to output the content for this page.
+* @param callable $callback   Optional. The function to be called to output the content for this page.
-* @param int      $position   The position in the menu order this item should appear.
+* @param int      $position   Optional. The position in the menu order this item should appear.
 * @return string|false The resulting page's hook_suffix, or false if the user does not have the capability required.
 */
-function add_comments_page( $page_title, $menu_title, $capability, $menu_slug, $function = '', $position = null ) {
+function add_comments_page( $page_title, $menu_title, $capability, $menu_slug, $callback = '', $position = null ) {
-	return add_submenu_page( 'edit-comments.php', $page_title, $menu_title, $capability, $menu_slug, $function, $position );
+	return add_submenu_page( 'edit-comments.php', $page_title, $menu_title, $capability, $menu_slug, $callback, $position );
 }
 /**
-* Remove a top-level admin menu.
+* Removes a top-level admin menu.
+*
+* Example usage:
+*
+*  - `remove_menu_page( 'tools.php' )`
+*  - `remove_menu_page( 'plugin_menu_slug' )`
 *
 * @since 3.1.0
 *
 * @global array $menu
 *
 	return false;
 }
 /**
-* Remove an admin submenu.
+* Removes an admin submenu.
+*
+* Example usage:
+*
+*  - `remove_submenu_page( 'themes.php', 'nav-menus.php' )`
+*  - `remove_submenu_page( 'tools.php', 'plugin_submenu_slug' )`
+*  - `remove_submenu_page( 'plugin_menu_slug', 'plugin_submenu_slug' )`
 *
 * @since 3.1.0
 *
 * @global array $submenu
 *
 	return false;
 }
 /**
-* Get the URL to access a particular menu page based on the slug it was registered with.
+* Gets the URL to access a particular menu page based on the slug it was registered with.
 *
 * If the slug hasn't been registered properly, no URL will be returned.
 *
 * @since 3.0.0
 *
 * @global array $_parent_pages
 *
 * @param string $menu_slug The slug name to refer to this menu by (should be unique for this menu).
-* @param bool   $echo      Whether or not to echo the URL. Default true.
+* @param bool   $display   Optional. Whether or not to display the URL. Default true.
 * @return string The menu page URL.
 */
-function menu_page_url( $menu_slug, $echo = true ) {
+function menu_page_url( $menu_slug, $display = true ) {
 	global $_parent_pages;
 	if ( isset( $_parent_pages[ $menu_slug ] ) ) {
 		$parent_slug = $_parent_pages[ $menu_slug ];
 		$url = '';
 	}
 	$url = esc_url( $url );
-	if ( $echo ) {
+	if ( $display ) {
 		echo $url;
 	}
 	return $url;
 }
 * @since 1.5.0
 *
 * @global string $parent_file
 * @global array  $menu
 * @global array  $submenu
-* @global string $pagenow
+* @global string $pagenow              The filename of the current screen.
-* @global string $typenow
+* @global string $typenow              The post type of the current screen.
 * @global string $plugin_page
 * @global array  $_wp_real_parent_file
 * @global array  $_wp_menu_nopriv
 * @global array  $_wp_submenu_nopriv
 *
-* @param string $parent The slug name for the parent menu (or the file name of a standard
+* @param string $parent_page Optional. The slug name for the parent menu (or the file name
-*                       WordPress admin page). Default empty string.
+*                            of a standard WordPress admin page). Default empty string.
 * @return string The parent file of the current admin page.
 */
-function get_admin_page_parent( $parent = '' ) {
+function get_admin_page_parent( $parent_page = '' ) {
 	global $parent_file, $menu, $submenu, $pagenow, $typenow,
 		$plugin_page, $_wp_real_parent_file, $_wp_menu_nopriv, $_wp_submenu_nopriv;
-	if ( ! empty( $parent ) && 'admin.php' !== $parent ) {
+	if ( ! empty( $parent_page ) && 'admin.php' !== $parent_page ) {
-		if ( isset( $_wp_real_parent_file[ $parent ] ) ) {
+		if ( isset( $_wp_real_parent_file[ $parent_page ] ) ) {
-			$parent = $_wp_real_parent_file[ $parent ];
+			$parent_page = $_wp_real_parent_file[ $parent_page ];
 		}
-		return $parent;
+		return $parent_page;
 	}
 	if ( 'admin.php' === $pagenow && isset( $plugin_page ) ) {
 		foreach ( (array) $menu as $parent_menu ) {
 			if ( $parent_menu[2] === $plugin_page ) {
 		}
 		return $parent_file;
 	}
-	foreach ( array_keys( (array) $submenu ) as $parent ) {
+	foreach ( array_keys( (array) $submenu ) as $parent_page ) {
-		foreach ( $submenu[ $parent ] as $submenu_array ) {
+		foreach ( $submenu[ $parent_page ] as $submenu_array ) {
-			if ( isset( $_wp_real_parent_file[ $parent ] ) ) {
+			if ( isset( $_wp_real_parent_file[ $parent_page ] ) ) {
-				$parent = $_wp_real_parent_file[ $parent ];
+				$parent_page = $_wp_real_parent_file[ $parent_page ];
 			}
 			if ( ! empty( $typenow ) && "$pagenow?post_type=$typenow" === $submenu_array[2] ) {
-				$parent_file = $parent;
+				$parent_file = $parent_page;
-				return $parent;
+				return $parent_page;
 			} elseif ( empty( $typenow ) && $pagenow === $submenu_array[2]
 				&& ( empty( $parent_file ) || false === strpos( $parent_file, '?' ) )
 			) {
-				$parent_file = $parent;
+				$parent_file = $parent_page;
-				return $parent;
+				return $parent_page;
 			} elseif ( isset( $plugin_page ) && $plugin_page === $submenu_array[2] ) {
-				$parent_file = $parent;
+				$parent_file = $parent_page;
-				return $parent;
+				return $parent_page;
 			}
 		}
 	}
 	if ( empty( $parent_file ) ) {
 * Gets the title of the current admin page.
 *
 * @since 1.5.0
 *
 * @global string $title
-* @global array $menu
+* @global array  $menu
-* @global array $submenu
+* @global array  $submenu
-* @global string $pagenow
+* @global string $pagenow     The filename of the current screen.
+* @global string $typenow     The post type of the current screen.
 * @global string $plugin_page
-* @global string $typenow
 *
 * @return string The title of the current admin page.
 */
 function get_admin_page_title() {
-	global $title, $menu, $submenu, $pagenow, $plugin_page, $typenow;
+	global $title, $menu, $submenu, $pagenow, $typenow, $plugin_page;
 	if ( ! empty( $title ) ) {
 		return $title;
 	}
 /**
 * Determines whether the current user can access the current admin page.
 *
 * @since 1.5.0
 *
-* @global string $pagenow
+* @global string $pagenow            The filename of the current screen.
 * @global array  $menu
 * @global array  $submenu
 * @global array  $_wp_menu_nopriv
 * @global array  $_wp_submenu_nopriv
 * @global string $plugin_page
 	return $allowed_options;
 }
 /**
-* Output nonce, action, and option_page fields for a settings page.
+* Outputs nonce, action, and option_page fields for a settings page.
 *
 * @since 2.7.0
 *
 * @param string $option_group A settings group name. This should match the group name
 *                             used in register_setting().
 	}
 	wp_cache_delete( 'plugins', 'plugins' );
 }
 /**
-* Load a given plugin attempt to generate errors.
+* Loads a given plugin attempt to generate errors.
 *
 * @since 3.0.0
 * @since 4.4.0 Function was moved into the `wp-admin/includes/plugin.php` file.
 *
 * @param string $plugin Path to the plugin file relative to the plugins directory.
 	wp_register_plugin_realpath( WP_PLUGIN_DIR . '/' . $plugin );
 	include_once WP_PLUGIN_DIR . '/' . $plugin;
 }
 /**
-* Helper function for adding content to the Privacy Policy Guide.
+* Declares a helper function for adding content to the Privacy Policy Guide.
 *
 * Plugins and themes should suggest text for inclusion in the site's privacy policy.
 * The suggested text should contain information about any functionality that affects user privacy,
 * and will be shown on the Privacy Policy Guide screen.
 *
 /**
 * Renders an admin notice in case some plugins have been paused due to errors.
 *
 * @since 5.2.0
 *
-* @global string $pagenow
+* @global string $pagenow The filename of the current screen.
 */
 function paused_plugins_notice() {
 	if ( 'plugins.php' === $GLOBALS['pagenow'] ) {
 		return;
 	}
 * upgrade due to incompatibility with the current version of WordPress.
 *
 * @since 5.8.0
 * @access private
 *
-* @global string $pagenow
+* @global string $pagenow    The filename of the current screen.
-* @global string $wp_version
+* @global string $wp_version The WordPress version string.
 */
 function deactivated_plugins_notice() {
 	if ( 'plugins.php' === $GLOBALS['pagenow'] ) {
 		return;
 	}
 	$deactivated_plugins = array_merge( $blog_deactivated_plugins, $site_deactivated_plugins );
 	foreach ( $deactivated_plugins as $plugin ) {
 		if ( ! empty( $plugin['version_compatible'] ) && ! empty( $plugin['version_deactivated'] ) ) {
 			$explanation = sprintf(
-				/* translators: 1: Name of deactivated plugin, 2: Plugin version deactivated, 3: Current WP version, 4: Compatible plugin version */
+				/* translators: 1: Name of deactivated plugin, 2: Plugin version deactivated, 3: Current WP version, 4: Compatible plugin version. */
 				__( '%1$s %2$s was deactivated due to incompatibility with WordPress %3$s, please upgrade to %1$s %4$s or later.' ),
 				$plugin['plugin_name'],
 				$plugin['version_deactivated'],
 				$GLOBALS['wp_version'],
 				$plugin['version_compatible']
 			);
 		} else {
 			$explanation = sprintf(
-				/* translators: 1: Name of deactivated plugin, 2: Plugin version deactivated, 3: Current WP version */
+				/* translators: 1: Name of deactivated plugin, 2: Plugin version deactivated, 3: Current WP version. */
 				__( '%1$s %2$s was deactivated due to incompatibility with WordPress %3$s.' ),
 				$plugin['plugin_name'],
 				! empty( $plugin['version_deactivated'] ) ? $plugin['version_deactivated'] : '',
 				$GLOBALS['wp_version'],
 				$plugin['version_compatible']
 		}
 		printf(
 			'<div class="notice notice-warning"><p><strong>%s</strong><br>%s</p><p><a href="%s">%s</a></p></div>',
 			sprintf(
-				/* translators: %s: Name of deactivated plugin */
+				/* translators: %s: Name of deactivated plugin. */
 				__( '%s plugin deactivated during WordPress upgrade.' ),
 				$plugin['plugin_name']
 			),
 			$explanation,
 			esc_url( admin_url( 'plugins.php?plugin_status=inactive' ) ),

changeset 19	3d72ae0968f4
parent 18	be944660c56a
child 21	48c4eec2b7e6