From 19ef699ec58b904bb500470287de45829003ca2a Mon Sep 17 00:00:00 2001
From: Sergey Biryukov <sergeybiryukov@git.wordpress.org>
Date: Mon, 1 Apr 2019 14:08:01 +0000
Subject: [PATCH] Docs: Improve documentation for `get_plugin_page_hook()` and
 `get_plugin_page_hookname()`.

Props subrataemfluence, desrosj.
Fixes #44224.

git-svn-id: https://develop.svn.wordpress.org/trunk@45085 602fd350-edb4-49c9-b593-d223f7449a82
---
 src/wp-admin/includes/plugin.php | 24 +++++++++++++++++-------
 1 file changed, 17 insertions(+), 7 deletions(-)

diff --git a/src/wp-admin/includes/plugin.php b/src/wp-admin/includes/plugin.php
index 23bc994749..54c6db27ac 100644
--- a/src/wp-admin/includes/plugin.php
+++ b/src/wp-admin/includes/plugin.php
@@ -1354,8 +1354,8 @@ function add_submenu_page( $parent_slug, $page_title, $menu_title, $capability,
 	$_registered_pages[ $hookname ] = true;
 
 	/*
-	 * Backward-compatibility for plugins using add_management page.
-	 * See wp-admin/admin.php for redirect from edit.php to tools.php
+	 * Backward-compatibility for plugins using add_management_page().
+	 * See wp-admin/admin.php for redirect from edit.php to tools.php.
 	 */
 	if ( 'tools.php' == $parent_slug ) {
 		$_registered_pages[ get_plugin_page_hookname( $menu_slug, 'edit.php' ) ] = true;
@@ -1713,6 +1713,8 @@ function menu_page_url( $menu_slug, $echo = true ) {
  * @global array $_wp_real_parent_file
  * @global array $_wp_menu_nopriv
  * @global array $_wp_submenu_nopriv
+ *
+ * @return string
  */
 function get_admin_page_parent( $parent = '' ) {
 	global $parent_file, $menu, $submenu, $pagenow, $typenow,
@@ -1783,6 +1785,8 @@ function get_admin_page_parent( $parent = '' ) {
  * @global string $pagenow
  * @global string $plugin_page
  * @global string $typenow
+ *
+ * @return string
  */
 function get_admin_page_title() {
 	global $title, $menu, $submenu, $pagenow, $plugin_page, $typenow;
@@ -1859,9 +1863,10 @@ function get_admin_page_title() {
 /**
  * @since 2.3.0
  *
- * @param string $plugin_page
- * @param string $parent_page
- * @return string|null
+ * @param string $plugin_page The slug name of the plugin page.
+ * @param string $parent_page The slug name for the parent menu (or the file name of a standard
+ *                            WordPress admin page).
+ * @return string|null Hook attached to the plugin page, null otherwise.
  */
 function get_plugin_page_hook( $plugin_page, $parent_page ) {
 	$hook = get_plugin_page_hookname( $plugin_page, $parent_page );
@@ -1874,8 +1879,11 @@ function get_plugin_page_hook( $plugin_page, $parent_page ) {
 
 /**
  * @global array $admin_page_hooks
- * @param string $plugin_page
- * @param string $parent_page
+ *
+ * @param string $plugin_page The slug name of the plugin page.
+ * @param string $parent_page The slug name for the parent menu (or the file name of a standard
+ *                            WordPress admin page).
+ * @return string Hook name for the plugin page.
  */
 function get_plugin_page_hookname( $plugin_page, $parent_page ) {
 	global $admin_page_hooks;
@@ -1906,6 +1914,8 @@ function get_plugin_page_hookname( $plugin_page, $parent_page ) {
  * @global array $_wp_submenu_nopriv
  * @global string $plugin_page
  * @global array $_registered_pages
+ *
+ * @return bool Whether the current user can access the current admin page.
  */
 function user_can_access_admin_page() {
 	global $pagenow, $menu, $submenu, $_wp_menu_nopriv, $_wp_submenu_nopriv,