From 6babc3833b0a06cc09ca7643df09a5443b14059f Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Fri, 29 Oct 2021 23:13:05 +0000 Subject: [PATCH] Docs: Miscellaneous docblock improvements. See #53399 Built from https://develop.svn.wordpress.org/trunk@51955 git-svn-id: http://core.svn.wordpress.org/trunk@51544 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-admin/includes/plugin.php | 43 ++++++++++++++++++++++------------- wp-admin/includes/upgrade.php | 1 - wp-includes/cron.php | 4 ++-- wp-includes/formatting.php | 4 ++-- wp-includes/theme.php | 2 +- wp-includes/version.php | 2 +- wp-login.php | 24 +++++++++---------- 7 files changed, 45 insertions(+), 35 deletions(-) diff --git a/wp-admin/includes/plugin.php b/wp-admin/includes/plugin.php index 6e332c247e..0934d6b810 100644 --- a/wp-admin/includes/plugin.php +++ b/wp-admin/includes/plugin.php @@ -1278,7 +1278,7 @@ function uninstall_plugin( $plugin ) { // /** - * 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. @@ -1350,7 +1350,7 @@ function add_menu_page( $page_title, $menu_title, $capability, $menu_slug, $func } /** - * 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. @@ -1474,7 +1474,7 @@ function add_submenu_page( $parent_slug, $page_title, $menu_title, $capability, } /** - * 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. @@ -1498,7 +1498,7 @@ function add_management_page( $page_title, $menu_title, $capability, $menu_slug, } /** - * 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. @@ -1522,7 +1522,7 @@ function add_options_page( $page_title, $menu_title, $capability, $menu_slug, $f } /** - * 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. @@ -1546,7 +1546,7 @@ function add_theme_page( $page_title, $menu_title, $capability, $menu_slug, $fun } /** - * 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. @@ -1570,7 +1570,7 @@ function add_plugins_page( $page_title, $menu_title, $capability, $menu_slug, $f } /** - * 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. @@ -1599,7 +1599,7 @@ function add_users_page( $page_title, $menu_title, $capability, $menu_slug, $fun } /** - * 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. @@ -1623,7 +1623,7 @@ function add_dashboard_page( $page_title, $menu_title, $capability, $menu_slug, } /** - * 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. @@ -1647,7 +1647,7 @@ function add_posts_page( $page_title, $menu_title, $capability, $menu_slug, $fun } /** - * 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. @@ -1671,7 +1671,7 @@ function add_media_page( $page_title, $menu_title, $capability, $menu_slug, $fun } /** - * 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. @@ -1695,7 +1695,7 @@ function add_links_page( $page_title, $menu_title, $capability, $menu_slug, $fun } /** - * 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. @@ -1719,7 +1719,7 @@ function add_pages_page( $page_title, $menu_title, $capability, $menu_slug, $fun } /** - * 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. @@ -1743,7 +1743,12 @@ function add_comments_page( $page_title, $menu_title, $capability, $menu_slug, $ } /** - * 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 * @@ -1766,7 +1771,13 @@ function remove_menu_page( $menu_slug ) { } /** - * 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 * @@ -1794,7 +1805,7 @@ function remove_submenu_page( $menu_slug, $submenu_slug ) { } /** - * 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. * diff --git a/wp-admin/includes/upgrade.php b/wp-admin/includes/upgrade.php index b558819771..3be073f7af 100644 --- a/wp-admin/includes/upgrade.php +++ b/wp-admin/includes/upgrade.php @@ -1878,7 +1878,6 @@ function upgrade_370() { * * @ignore * @since 3.7.2 - * @since 3.8.0 * * @global int $wp_current_db_version The old (current) database version. */ diff --git a/wp-includes/cron.php b/wp-includes/cron.php index 41efeebc44..8e50349f5d 100644 --- a/wp-includes/cron.php +++ b/wp-includes/cron.php @@ -1040,7 +1040,7 @@ function _wp_cron() { * @since 2.1.0 * @since 5.4.0 The 'weekly' schedule was added. * - * @return array + * @return array[] */ function wp_get_schedules() { $schedules = array( @@ -1067,7 +1067,7 @@ function wp_get_schedules() { * * @since 2.1.0 * - * @param array $new_schedules An array of non-default cron schedules. Default empty. + * @param array[] $new_schedules An array of non-default cron schedule arrays. Default empty. */ return array_merge( apply_filters( 'cron_schedules', array() ), $schedules ); } diff --git a/wp-includes/formatting.php b/wp-includes/formatting.php index fa1fd8347f..d3903d46c4 100644 --- a/wp-includes/formatting.php +++ b/wp-includes/formatting.php @@ -3539,8 +3539,8 @@ function get_gmt_from_date( $string, $format = 'Y-m-d H:i:s' ) { /** * Given a date in UTC or GMT timezone, returns that date in the timezone of the site. * - * Requires and returns a date in the Y-m-d H:i:s format. - * Return format can be overridden using the $format parameter. + * Requires a date in the Y-m-d H:i:s format. + * Default return format of 'Y-m-d H:i:s' can be overridden using the `$format` parameter. * * @since 1.2.0 * diff --git a/wp-includes/theme.php b/wp-includes/theme.php index 384c056404..e233b4127a 100644 --- a/wp-includes/theme.php +++ b/wp-includes/theme.php @@ -3073,7 +3073,7 @@ function require_if_theme_supports( $feature, $include ) { * @type string $type The type of data associated with this feature. * Valid values are 'string', 'boolean', 'integer', * 'number', 'array', and 'object'. Defaults to 'boolean'. - * @type boolean $variadic Does this feature utilize the variadic support + * @type bool $variadic Does this feature utilize the variadic support * of add_theme_support(), or are all arguments specified * as the second parameter. Must be used with the "array" type. * @type string $description A short description of the feature. Included in diff --git a/wp-includes/version.php b/wp-includes/version.php index d3315cf5a4..bbdc27e64f 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -16,7 +16,7 @@ * * @global string $wp_version */ -$wp_version = '5.9-alpha-51954'; +$wp_version = '5.9-alpha-51955'; /** * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema. diff --git a/wp-login.php b/wp-login.php index 0d030863ed..b7c14b4c83 100644 --- a/wp-login.php +++ b/wp-login.php @@ -434,18 +434,18 @@ do_action( 'login_init' ); * * Possible hook names include: * - * - 'login_form_checkemail' - * - 'login_form_confirm_admin_email' - * - 'login_form_confirmaction' - * - 'login_form_entered_recovery_mode' - * - 'login_form_login' - * - 'login_form_logout' - * - 'login_form_lostpassword' - * - 'login_form_postpass' - * - 'login_form_register' - * - 'login_form_resetpass' - * - 'login_form_retrievepassword' - * - 'login_form_rp' + * - `login_form_checkemail` + * - `login_form_confirm_admin_email` + * - `login_form_confirmaction` + * - `login_form_entered_recovery_mode` + * - `login_form_login` + * - `login_form_logout` + * - `login_form_lostpassword` + * - `login_form_postpass` + * - `login_form_register` + * - `login_form_resetpass` + * - `login_form_retrievepassword` + * - `login_form_rp` * * @since 2.8.0 */