@return missing in doc comment of get_admin_page_parent function

[subrataemfluence]

@return is missing in the Doc comment of get_admin_page_parent function.

Also I have a question. At the end of the function body we are returning hard coded empty string i.e. return '';

Why don't we return the $parent_file instead? Since we are already returning the value from rest of the if-else blocks and foreach loop the last final statement either will return an empty string or a value assigned to $parent_file variable.

<?php
if( empty( $parent_file ) ) {
   $parent_file = '';
}

return $parent_file;

[subrataemfluence]

Since get_admin_page_title function is also missing the @return in Doc comment I am uploading a revised patch which combines both the functions.

[subrataemfluence]

Revised proposed patch.

[kennithnichol]

Given PHPs type coercion, this really could just return $parent_file; without any check for empty, the caller should be responsible for checking for empty().

Returning $parent_file could have unintended side-effects. The check for empty on $parent_file effects a global variable and does not necessarily have any correlation to the return statement.

[subrataemfluence]

@kennithnichol I understand the concern! Thank you for explaining and correcting me.

[SergeyBiryukov]

In 47006:

Docs: Improve documentation for admin menu functions:

• get_admin_page_parent()
• get_admin_page_title()
• get_plugin_page_hook()
• get_plugin_page_hookname()
• user_can_access_admin_page()

Add missing descriptions and @since tags.

Props subrataemfluence, kennithnichol, stevenlinx, SergeyBiryukov.
Fixes #44253, #49067.