From 3d86f8af55edb27591fb8d663a31e557fcf80dc4 Mon Sep 17 00:00:00 2001 From: John Blackbourn Date: Sat, 30 Oct 2021 20:26:59 +0000 Subject: [PATCH] Application Passwords: Various docblock improvements. See #53399, #42790 Built from https://develop.svn.wordpress.org/trunk@51958 git-svn-id: http://core.svn.wordpress.org/trunk@51547 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- .../class-wp-application-passwords.php | 50 +++++++++++++++---- wp-includes/rest-api.php | 2 +- ...-rest-application-passwords-controller.php | 14 +++--- wp-includes/version.php | 2 +- 4 files changed, 50 insertions(+), 18 deletions(-) diff --git a/wp-includes/class-wp-application-passwords.php b/wp-includes/class-wp-application-passwords.php index a86660b27b..fd7fac2162 100644 --- a/wp-includes/class-wp-application-passwords.php +++ b/wp-includes/class-wp-application-passwords.php @@ -43,7 +43,7 @@ class WP_Application_Passwords { /** * Checks if Application Passwords are being used by the site. * - * This returns true if at least one App Password has ever been created. + * This returns true if at least one Application Password has ever been created. * * @since 5.6.0 * @@ -61,7 +61,12 @@ class WP_Application_Passwords { * @since 5.7.0 Returns WP_Error if application name already exists. * * @param int $user_id User ID. - * @param array $args Information about the application password. + * @param array $args { + * Arguments used to create the application password. + * + * @type string $name The name of the application password. + * @type string $app_id A UUID provided by the application to uniquely identify it. + * } * @return array|WP_Error The first key in the array is the new password, the second is its detailed information. * A WP_Error instance is returned on error. */ @@ -110,9 +115,24 @@ class WP_Application_Passwords { * @since 5.6.0 * * @param int $user_id The user ID. - * @param array $new_item The details about the created password. - * @param string $new_password The unhashed generated app password. - * @param array $args Information used to create the application password. + * @param array $new_item { + * The details about the created password. + * + * @type string $uuid The unique identifier for the application password. + * @type string $app_id A UUID provided by the application to uniquely identify it. + * @type string $name The name of the application password. + * @type string $password A one-way hash of the password. + * @type int $created Unix timestamp of when the password was created. + * @type null $last_used Null. + * @type null $last_ip Null. + * } + * @param string $new_password The unhashed generated application password. + * @param array $args { + * Arguments used to create the application password. + * + * @type string $name The name of the application password. + * @type string $app_id A UUID provided by the application to uniquely identify it. + * } */ do_action( 'wp_create_application_password', $user_id, $new_item, $new_password, $args ); @@ -125,7 +145,19 @@ class WP_Application_Passwords { * @since 5.6.0 * * @param int $user_id User ID. - * @return array The list of app passwords. + * @return array { + * The list of app passwords. + * + * @type array ...$0 { + * @type string $uuid The unique identifier for the application password. + * @type string $app_id A UUID provided by the application to uniquely identify it. + * @type string $name The name of the application password. + * @type string $password A one-way hash of the password. + * @type int $created Unix timestamp of when the password was created. + * @type int|null $last_used The Unix timestamp of the GMT date the application password was last used. + * @type string|null $last_ip The IP address the application password was last used by. + * } + * } */ public static function get_user_application_passwords( $user_id ) { $passwords = get_user_meta( $user_id, static::USERMETA_KEY_APPLICATION_PASSWORDS, true ); @@ -172,13 +204,13 @@ class WP_Application_Passwords { } /** - * Checks if application name exists for this user. + * Checks if an application password with the given name exists for this user. * * @since 5.7.0 * * @param int $user_id User ID. * @param string $name Application name. - * @return bool Whether provided application name exists or not. + * @return bool Whether the provided application name exists. */ public static function application_name_exists_for_user( $user_id, $name ) { $passwords = static::get_user_application_passwords( $user_id ); @@ -352,7 +384,7 @@ class WP_Application_Passwords { } /** - * Sets a users application passwords. + * Sets a user's application passwords. * * @since 5.6.0 * diff --git a/wp-includes/rest-api.php b/wp-includes/rest-api.php index 7e66ecd801..3d89f16009 100644 --- a/wp-includes/rest-api.php +++ b/wp-includes/rest-api.php @@ -1091,7 +1091,7 @@ function rest_application_password_collect_status( $user_or_error, $app_password * * @global string|null $wp_rest_application_password_uuid * - * @return string|null The App Password UUID, or null if Application Passwords was not used. + * @return string|null The Application Password UUID, or null if Application Passwords was not used. */ function rest_get_authenticated_app_password() { global $wp_rest_application_password_uuid; diff --git a/wp-includes/rest-api/endpoints/class-wp-rest-application-passwords-controller.php b/wp-includes/rest-api/endpoints/class-wp-rest-application-passwords-controller.php index ecdc221b5f..bdf1959c62 100644 --- a/wp-includes/rest-api/endpoints/class-wp-rest-application-passwords-controller.php +++ b/wp-includes/rest-api/endpoints/class-wp-rest-application-passwords-controller.php @@ -356,7 +356,7 @@ class WP_REST_Application_Passwords_Controller extends WP_REST_Controller { } /** - * Checks if a given request has access to delete all application passwords. + * Checks if a given request has access to delete all application passwords for a user. * * @since 5.6.0 * @@ -382,7 +382,7 @@ class WP_REST_Application_Passwords_Controller extends WP_REST_Controller { } /** - * Deletes all application passwords. + * Deletes all application passwords for a user. * * @since 5.6.0 * @@ -411,7 +411,7 @@ class WP_REST_Application_Passwords_Controller extends WP_REST_Controller { } /** - * Checks if a given request has access to delete a specific application password. + * Checks if a given request has access to delete a specific application password for a user. * * @since 5.6.0 * @@ -437,7 +437,7 @@ class WP_REST_Application_Passwords_Controller extends WP_REST_Controller { } /** - * Deletes one application password. + * Deletes an application password for a user. * * @since 5.6.0 * @@ -474,7 +474,7 @@ class WP_REST_Application_Passwords_Controller extends WP_REST_Controller { } /** - * Checks if a given request has access to get the currently used application password. + * Checks if a given request has access to get the currently used application password for a user. * * @since 5.7.0 * @@ -500,7 +500,7 @@ class WP_REST_Application_Passwords_Controller extends WP_REST_Controller { } /** - * Retrieves the application password being currently used for authentication. + * Retrieves the application password being currently used for authentication of a user. * * @since 5.7.0 * @@ -723,7 +723,7 @@ class WP_REST_Application_Passwords_Controller extends WP_REST_Controller { } /** - * Gets the requested application password. + * Gets the requested application password for a user. * * @since 5.6.0 * diff --git a/wp-includes/version.php b/wp-includes/version.php index 7937cf75b2..a66a0224ab 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -16,7 +16,7 @@ * * @global string $wp_version */ -$wp_version = '5.9-alpha-51957'; +$wp_version = '5.9-alpha-51958'; /** * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.