From 6e15f7fc9a7b30323e7f36aa92e8b5468145e077 Mon Sep 17 00:00:00 2001 From: Sergey Biryukov Date: Mon, 23 May 2022 15:01:12 +0000 Subject: [PATCH] Docs: Use third-person singular verbs for method descriptions in `wp-includes/class-wp-roles.php`, per the documentation standards. See #55646. Built from https://develop.svn.wordpress.org/trunk@53436 git-svn-id: http://core.svn.wordpress.org/trunk@53025 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-includes/capabilities.php | 3 ++- wp-includes/class-wp-roles.php | 35 +++++++++++++++++----------------- wp-includes/version.php | 2 +- 3 files changed, 21 insertions(+), 19 deletions(-) diff --git a/wp-includes/capabilities.php b/wp-includes/capabilities.php index 5eea17197a..d06887a2bb 100644 --- a/wp-includes/capabilities.php +++ b/wp-includes/capabilities.php @@ -1020,12 +1020,13 @@ function get_role( $role ) { * @param string $display_name Display name for role. * @param bool[] $capabilities List of capabilities keyed by the capability name, * e.g. array( 'edit_posts' => true, 'delete_posts' => false ). - * @return WP_Role|null WP_Role object if role is added, null if already exists. + * @return WP_Role|void WP_Role object, if the role is added. */ function add_role( $role, $display_name, $capabilities = array() ) { if ( empty( $role ) ) { return; } + return wp_roles()->add_role( $role, $display_name, $capabilities ); } diff --git a/wp-includes/class-wp-roles.php b/wp-includes/class-wp-roles.php index aa52a106ad..23d5d76723 100644 --- a/wp-includes/class-wp-roles.php +++ b/wp-includes/class-wp-roles.php @@ -73,7 +73,7 @@ class WP_Roles { protected $site_id = 0; /** - * Constructor + * Constructor. * * @since 2.0.0 * @since 4.9.0 The `$site_id` argument was added. @@ -91,7 +91,7 @@ class WP_Roles { } /** - * Make private/protected methods readable for backward compatibility. + * Makes private/protected methods readable for backward compatibility. * * @since 4.0.0 * @@ -107,7 +107,7 @@ class WP_Roles { } /** - * Set up the object properties. + * Sets up the object properties. * * The role key is set to the current prefix for the $wpdb object with * 'user_roles' appended. If the $wp_user_roles global is set, then it will @@ -123,7 +123,7 @@ class WP_Roles { } /** - * Reinitialize the object + * Reinitializes the object. * * Recreates the role objects. This is typically called only by switch_to_blog() * after switching wpdb to a new site ID. @@ -138,20 +138,21 @@ class WP_Roles { } /** - * Add role name with capabilities to list. + * Adds a role name with capabilities to the list. * * Updates the list of roles, if the role doesn't already exist. * - * The capabilities are defined in the following format `array( 'read' => true );` - * To explicitly deny a role a capability you set the value for that capability to false. + * The capabilities are defined in the following format: `array( 'read' => true )`. + * To explicitly deny the role a capability, set the value for that capability to false. * * @since 2.0.0 * * @param string $role Role name. * @param string $display_name Role display name. - * @param bool[] $capabilities List of capabilities keyed by the capability name, - * e.g. array( 'edit_posts' => true, 'delete_posts' => false ). - * @return WP_Role|void WP_Role object, if role is added. + * @param bool[] $capabilities Optional. List of capabilities keyed by the capability name, + * e.g. `array( 'edit_posts' => true, 'delete_posts' => false )`. + * Default empty array. + * @return WP_Role|void WP_Role object, if the role is added. */ public function add_role( $role, $display_name, $capabilities = array() ) { if ( empty( $role ) || isset( $this->roles[ $role ] ) ) { @@ -171,7 +172,7 @@ class WP_Roles { } /** - * Remove role by name. + * Removes a role by name. * * @since 2.0.0 * @@ -196,7 +197,7 @@ class WP_Roles { } /** - * Add capability to role. + * Adds a capability to role. * * @since 2.0.0 * @@ -217,7 +218,7 @@ class WP_Roles { } /** - * Remove capability from role. + * Removes a capability from role. * * @since 2.0.0 * @@ -236,7 +237,7 @@ class WP_Roles { } /** - * Retrieve role object by name. + * Retrieves a role object by name. * * @since 2.0.0 * @@ -252,7 +253,7 @@ class WP_Roles { } /** - * Retrieve list of role names. + * Retrieves a list of role names. * * @since 2.0.0 * @@ -263,7 +264,7 @@ class WP_Roles { } /** - * Whether role name is currently in the list of available roles. + * Determines whether a role name is currently in the list of available roles. * * @since 2.0.0 * @@ -292,7 +293,7 @@ class WP_Roles { } /** - * After the roles have been initialized, allow plugins to add their own roles. + * Fires after the roles have been initialized, allowing plugins to add their own roles. * * @since 4.7.0 * diff --git a/wp-includes/version.php b/wp-includes/version.php index 82ebe68494..137670f306 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -16,7 +16,7 @@ * * @global string $wp_version */ -$wp_version = '6.1-alpha-53435'; +$wp_version = '6.1-alpha-53436'; /** * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.