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
This commit is contained in:
audrasjb 2022-04-14 07:08:08 +00:00
parent 050a2947cf
commit c5a34f9397
2 changed files with 47 additions and 47 deletions

View File

@ -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
*

View File

@ -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.