From c5a34f9397b81b605161290b6455eaac4f7cbf52 Mon Sep 17 00:00:00 2001 From: audrasjb Date: Thu, 14 Apr 2022 07:08:08 +0000 Subject: [PATCH] Docs: Misc. Docblocks improvements in the Core User API. See #54729. Built from https://develop.svn.wordpress.org/trunk@53179 git-svn-id: http://core.svn.wordpress.org/trunk@52768 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-includes/user.php | 92 ++++++++++++++++++++--------------------- wp-includes/version.php | 2 +- 2 files changed, 47 insertions(+), 47 deletions(-) diff --git a/wp-includes/user.php b/wp-includes/user.php index 4a22e5ca7f..0511a8a890 100644 --- a/wp-includes/user.php +++ b/wp-includes/user.php @@ -112,7 +112,7 @@ function wp_signon( $credentials = array(), $secure_cookie = '' ) { } /** - * Authenticate a user, confirming the username and password are valid. + * Authenticates a user, confirming the username and password are valid. * * @since 2.8.0 * @@ -158,7 +158,7 @@ function wp_authenticate_username_password( $user, $username, $password ) { } /** - * Filters whether the given user can be authenticated with the provided $password. + * Filters whether the given user can be authenticated with the provided password. * * @since 2.5.0 * @@ -261,7 +261,7 @@ function wp_authenticate_email_password( $user, $email, $password ) { } /** - * Authenticate the user using the WordPress auth cookie. + * Authenticates the user using the WordPress auth cookie. * * @since 2.8.0 * @@ -385,7 +385,7 @@ function wp_authenticate_application_password( $input_user, $username, $password } /* - * Strip out anything non-alphanumeric. This is so passwords can be used with + * Strips out anything non-alphanumeric. This is so passwords can be used with * or without spaces to indicate the groupings for readability. * * Generated application passwords are exclusively alphanumeric. @@ -482,7 +482,7 @@ function wp_validate_application_password( $input_user ) { } /** - * For Multisite blogs, check if the authenticated user has been marked as a + * For Multisite blogs, checks if the authenticated user has been marked as a * spammer, or if the user's primary blog has been marked as spam. * * @since 3.7.0 @@ -537,7 +537,7 @@ function wp_validate_logged_in_cookie( $user_id ) { } /** - * Number of posts user has written. + * Gets the number of posts a user has written. * * @since 3.0.0 * @since 4.1.0 Added `$post_type` argument. @@ -574,7 +574,7 @@ function count_user_posts( $userid, $post_type = 'post', $public_only = false ) } /** - * Number of posts written by a list of users. + * Gets the number of posts written by a list of users. * * @since 3.0.0 * @@ -615,7 +615,7 @@ function count_many_users_posts( $users, $post_type = 'post', $public_only = fal // /** - * Get the current user's ID + * Gets the current user's ID. * * @since MU (3.0.0) * @@ -630,7 +630,7 @@ function get_current_user_id() { } /** - * Retrieve user option that can be either per Site or per Network. + * Retrieves user option that can be either per Site or per Network. * * If the user ID is not given, then the current user will be used instead. If * the user ID is given, then the user data will be retrieved. The filter for @@ -688,7 +688,7 @@ function get_user_option( $option, $user = 0, $deprecated = '' ) { } /** - * Update user option with global blog capability. + * Updates user option with global blog capability. * * User options are just like user metadata except that they have support for * global blog options. If the 'global' parameter is false, which it is by default @@ -719,7 +719,7 @@ function update_user_option( $user_id, $option_name, $newvalue, $global = false } /** - * Delete user option with global blog capability. + * Deletes user option with global blog capability. * * User options are just like user metadata except that they have support for * global blog options. If the 'global' parameter is false, which it is by default @@ -745,7 +745,7 @@ function delete_user_option( $user_id, $option_name, $global = false ) { } /** - * Retrieve list of users matching criteria. + * Retrieves list of users matching criteria. * * @since 3.1.0 * @@ -766,7 +766,7 @@ function get_users( $args = array() ) { } /** - * List all the users of the site, with several options available. + * Lists all the users of the site, with several options available. * * @since 5.9.0 * @@ -886,7 +886,7 @@ function wp_list_users( $args = array() ) { } /** - * Get the sites a user belongs to. + * Gets the sites a user belongs to. * * @since 3.0.0 * @since 4.7.0 Converted to use `get_sites()`. @@ -1018,7 +1018,7 @@ function get_blogs_of_user( $user_id, $all = false ) { } /** - * Find out whether a user is a member of a given blog. + * Finds out whether a user is a member of a given blog. * * @since MU (3.0.0) * @@ -1100,7 +1100,7 @@ function add_user_meta( $user_id, $meta_key, $meta_value, $unique = false ) { } /** - * Remove metadata matching criteria from a user. + * Removes metadata matching criteria from a user. * * You can match based on the key, or key and value. Removing based on key and * value, will keep from removing duplicate metadata with the same key. It also @@ -1122,7 +1122,7 @@ function delete_user_meta( $user_id, $meta_key, $meta_value = '' ) { } /** - * Retrieve user meta field for a user. + * Retrieves user meta field for a user. * * @since 3.0.0 * @@ -1144,7 +1144,7 @@ function get_user_meta( $user_id, $key = '', $single = false ) { } /** - * Update user meta field based on user ID. + * Updates user meta field based on user ID. * * Use the $prev_value parameter to differentiate between meta fields with the * same key and user ID. @@ -1170,7 +1170,7 @@ function update_user_meta( $user_id, $meta_key, $meta_value, $prev_value = '' ) } /** - * Count number of users who have each of the user roles. + * Counts number of users who have each of the user roles. * * Assumes there are neither duplicated nor orphaned capabilities meta_values. * Assumes role names are unique phrases. Same assumption made by WP_User_Query::prepare_query() @@ -1454,7 +1454,7 @@ function wp_is_large_user_count( $network_id = null ) { // /** - * Set up global user vars. + * Sets up global user vars. * * Used by wp_set_current_user() for back compat. Might be deprecated in the future. * @@ -1499,7 +1499,7 @@ function setup_userdata( $for_user_id = 0 ) { } /** - * Create dropdown HTML content of users. + * Creates dropdown HTML content of users. * * The content can either be displayed, which it is by default or retrieved by * setting the 'echo' argument. The 'include' and 'exclude' arguments do not @@ -1709,7 +1709,7 @@ function wp_dropdown_users( $args = '' ) { } /** - * Sanitize user field based on context. + * Sanitizes user field based on context. * * Possible context values are: 'raw', 'edit', 'db', 'display', 'attribute' and 'js'. The * 'display' context is used by default. 'attribute' and 'js' contexts are treated like 'display' @@ -1827,7 +1827,7 @@ function sanitize_user_field( $field, $value, $user_id, $context ) { } /** - * Update all user caches + * Updates all user caches. * * @since 3.0.0 * @@ -1850,7 +1850,7 @@ function update_user_caches( $user ) { } /** - * Clean all user caches + * Cleans all user caches. * * @since 3.0.0 * @since 4.4.0 'clean_user_cache' action was added. @@ -1983,7 +1983,7 @@ function validate_username( $username ) { } /** - * Insert a user into the database. + * Inserts a user into the database. * * Most of the `$userdata` array fields have filters associated with the values. Exceptions are * 'ID', 'rich_editing', 'syntax_highlighting', 'comment_shortcuts', 'admin_color', 'use_ssl', @@ -2469,7 +2469,7 @@ function wp_insert_user( $userdata ) { } /** - * Update a user in the database. + * Updates a user in the database. * * It is possible to update a user's password by specifying the 'user_pass' * value in the $userdata parameter array. @@ -2709,7 +2709,7 @@ All at ###SITENAME### } /** - * A simpler way of inserting a user into the database. + * Provides a simpler way of inserting a user into the database. * * Creates a new user with just the username, password, and email. For more * complex user creation use wp_insert_user() to specify more information. @@ -2751,7 +2751,7 @@ function _get_additional_user_keys( $user ) { } /** - * Set up the user contact methods. + * Sets up the user contact methods. * * Default contact methods were removed in 3.6. A filter dictates contact methods. * @@ -2911,7 +2911,7 @@ function get_password_reset_key( $user ) { } /** - * Retrieves a user row based on password reset key and login + * Retrieves a user row based on password reset key and login. * * A key is considered 'expired' if it exactly matches the value of the * user_activation_key field, rather than being matched after going through the @@ -3419,7 +3419,7 @@ function wp_send_new_user_notifications( $user_id, $notify = 'both' ) { } /** - * Retrieve the current session token from the logged_in cookie. + * Retrieves the current session token from the logged_in cookie. * * @since 4.0.0 * @@ -3431,7 +3431,7 @@ function wp_get_session_token() { } /** - * Retrieve a list of sessions for the current user. + * Retrieves a list of sessions for the current user. * * @since 4.0.0 * @@ -3443,7 +3443,7 @@ function wp_get_all_sessions() { } /** - * Remove the current session token from the database. + * Removes the current session token from the database. * * @since 4.0.0 */ @@ -3456,7 +3456,7 @@ function wp_destroy_current_session() { } /** - * Remove all but the current session token for the current user for the database. + * Removes all but the current session token for the current user for the database. * * @since 4.0.0 */ @@ -3469,7 +3469,7 @@ function wp_destroy_other_sessions() { } /** - * Remove all session tokens for the current user from the database. + * Removes all session tokens for the current user from the database. * * @since 4.0.0 */ @@ -3479,7 +3479,7 @@ function wp_destroy_all_sessions() { } /** - * Get the user IDs of all users with no role on this site. + * Gets the user IDs of all users with no role on this site. * * @since 4.4.0 * @since 4.9.0 The `$site_id` parameter was added to support multisite. @@ -3592,7 +3592,7 @@ function _wp_get_current_user() { } /** - * Send a confirmation request email when a change of user email address is attempted. + * Sends a confirmation request email when a change of user email address is attempted. * * @since 3.0.0 * @since 4.9.0 This function was moved from wp-admin/includes/ms.php so it's no longer Multisite specific. @@ -3723,7 +3723,7 @@ function new_user_email_admin_notice() { } /** - * Get all personal data request types. + * Gets all personal data request types. * * @since 4.9.6 * @access private @@ -3829,7 +3829,7 @@ function wp_user_personal_data_exporter( $email_address ) { $reserved_names = array_values( $user_props_to_export ); /** - * Filter to extend the user's profile data for the privacy exporter. + * Filters the user's profile data for the privacy exporter. * * @since 5.4.0 * @@ -3953,7 +3953,7 @@ function wp_user_personal_data_exporter( $email_address ) { } /** - * Update log when privacy request is confirmed. + * Updates log when privacy request is confirmed. * * @since 4.9.6 * @access private @@ -3981,7 +3981,7 @@ function _wp_privacy_account_request_confirmed( $request_id ) { } /** - * Notify the site administrator via email when a request is confirmed. + * Notifies the site administrator via email when a request is confirmed. * * Without this, the admin would have to manually check the site to see if any * action was needed on their part yet. @@ -4194,7 +4194,7 @@ All at ###SITENAME### } /** - * Notify the user when their erasure request is fulfilled. + * Notifies the user when their erasure request is fulfilled. * * Without this, the user would never know if their data was actually erased. * @@ -4467,7 +4467,7 @@ All at ###SITENAME### } /** - * Return request confirmation message HTML. + * Returns request confirmation message HTML. * * @since 4.9.6 * @access private @@ -4505,7 +4505,7 @@ function _wp_privacy_account_request_confirmed_message( $request_id ) { } /** - * Create and log a user request to perform a specific action. + * Creates and logs a user request to perform a specific action. * * Requests are stored inside a post type named `user_request` since they can apply to both * users on the site, or guests without a user account. @@ -4576,7 +4576,7 @@ function wp_create_user_request( $email_address = '', $action_name = '', $reques } /** - * Get action description from the name and return a string. + * Gets action description from the name and return a string. * * @since 4.9.6 * @@ -4794,7 +4794,7 @@ function wp_generate_user_request_key( $request_id ) { } /** - * Validate a user request by comparing the key with the request's key. + * Validates a user request by comparing the key with the request's key. * * @since 4.9.6 * @@ -4849,7 +4849,7 @@ function wp_validate_user_request_key( $request_id, $key ) { } /** - * Return the user request object for the specified request ID. + * Returns the user request object for the specified request ID. * * @since 4.9.6 * diff --git a/wp-includes/version.php b/wp-includes/version.php index 63c3763025..a5e1a8c0dc 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -16,7 +16,7 @@ * * @global string $wp_version */ -$wp_version = '6.0-beta1-53178'; +$wp_version = '6.0-beta1-53179'; /** * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.