WordPress.org

Make WordPress Core

Changeset 27353


Ignore:
Timestamp:
03/02/2014 07:39:38 PM (7 years ago)
Author:
DrewAPicture
Message:

Inline documentation improvements for wp-includes/user.php.

Props morganestes, SergeyBiryukov.
Fixes #26148.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-includes/user.php

    r27351 r27353  
    44 *
    55 * @package WordPress
     6 * @subpackage Users
    67 */
    78
    … …  
    2122 * @param array $credentials Optional. User info in order to sign on.
    2223 * @param bool $secure_cookie Optional. Whether to use secure cookie.
    23  * @return object Either WP_Error on failure, or WP_User on success.
     24 * @return WP_User|WP_Error WP_User on success, WP_Error on failure.
    2425 */
    2526function wp_signon( $credentials = array(), $secure_cookie = '' ) {
    … …  
    3839        $credentials['remember'] = false;
    3940
    40     // TODO do we deprecate the wp_authentication action?
    4141    /**
    4242     * Fires before the user is authenticated.
    … …  
    4646     *
    4747     * @since 1.5.1
     48     *
     49     * @todo Decide whether to deprecate the wp_authenticate action.
    4850     *
    4951     * @param string $user_login    Username, passed by reference.
    … …  
    102104/**
    103105 * Authenticate the user using the username and password.
     106 *
     107 * @since 2.8.0
     108 *
     109 * @param WP_User|WP_Error|null $user     WP_User or WP_Error object from a previous callback. Default null.
     110 * @param string                $username Username for authentication.
     111 * @param string                $password Password for authentication.
     112 * @return WP_User|WP_Error WP_User on success, WP_Error on failure.
    104113 */
    105114function wp_authenticate_username_password($user, $username, $password) {
    … …  
    150159/**
    151160 * Authenticate the user using the WordPress auth cookie.
     161 *
     162 * @since 2.8.0
     163 *
     164 * @param WP_User|WP_Error|null $user     WP_User or WP_Error object from a previous callback. Default null.
     165 * @param string                $username Username. If passed, cancels the cookie authentication.
     166 * @param string                $password Password. If passed, cancels the cookie authentication.
     167 * @return WP_User|WP_Error WP_User on success, WP_Error on failure.
    152168 */
    153169function wp_authenticate_cookie($user, $username, $password) {
    … …  
    178194
    179195/**
    180  * For multisite blogs, check if the authenticated user has been marked as a
     196 * For Multisite blogs, check if the authenticated user has been marked as a
    181197 * spammer, or if the user's primary blog has been marked as spam.
    182198 *
    183199 * @since 3.7.0
     200 *
     201 * @param WP_User|WP_Error|null $user WP_User or WP_Error object from a previous callback. Default null.
     202 * @return WP_User|WP_Error WP_User on success, WP_Error if the user is considered a spammer.
    184203 */
    185204function wp_authenticate_spam_check( $user ) {
    … …  
    205224 *
    206225 * @since 3.0.0
    207  * @uses $wpdb WordPress database object for queries.
     226 *
     227 * @global wpdb $wpdb WordPress database object for queries.
    208228 *
    209229 * @param int $userid User ID.
    … …  
    292312 *
    293313 * @since 2.0.0
    294  * @uses $wpdb WordPress database object for queries.
    295  * @uses apply_filters() Calls 'get_user_option_$option' hook with result,
    296  *      option parameter, and user data object.
    297  *
    298  * @param string $option User option name.
    299  * @param int $user Optional. User ID.
    300  * @param bool $deprecated Use get_option() to check for an option in the options table.
    301  * @return mixed
     314 *
     315 * @global wpdb $wpdb WordPress database object for queries.
     316 *
     317 * @param string $option     User option name.
     318 * @param int    $user       Optional. User ID.
     319 * @param bool   $deprecated Use get_option() to check for an option in the options table.
     320 * @return mixed User option value on success, false on failure.
    302321 */
    303322function get_user_option( $option, $user = 0, $deprecated = '' ) {
    … …  
    345364 *
    346365 * @since 2.0.0
    347  * @uses $wpdb WordPress database object for queries
    348  *
    349  * @param int $user_id User ID
     366 *
     367 * @global wpdb $wpdb WordPress database object for queries.
     368 *
     369 * @param int    $user_id     User ID.
    350370 * @param string $option_name User option name.
    351  * @param mixed $newvalue User option value.
    352  * @param bool $global Optional. Whether option name is global or blog specific. Default false (blog specific).
    353  * @return unknown
     371 * @param mixed  $newvalue    User option value.
     372 * @param bool   $global      Optional. Whether option name is global or blog specific.
     373 *                            Default false (blog specific).
     374 * @return int|bool User meta ID if the option didn't exist, true on successful update,
     375 *                  false on failure.
    354376 */
    355377function update_user_option( $user_id, $option_name, $newvalue, $global = false ) {
    … …  
    370392 *
    371393 * @since 3.0.0
    372  * @uses $wpdb WordPress database object for queries
    373  *
    374  * @param int $user_id User ID
     394 *
     395 * @global wpdb $wpdb WordPress database object for queries.
     396 *
     397 * @param int    $user_id     User ID
    375398 * @param string $option_name User option name.
    376  * @param bool $global Optional. Whether option name is global or blog specific. Default false (blog specific).
    377  * @return unknown
     399 * @param bool   $global      Optional. Whether option name is global or blog specific.
     400 *                            Default false (blog specific).
     401 * @return bool True on success, false on failure.
    378402 */
    379403function delete_user_option( $user_id, $option_name, $global = false ) {
    … …  
    427451
    428452    /**
    429      * PHP5 constructor
     453     * PHP5 constructor.
    430454     *
    431455     * @since 3.1.0
    432456     *
    433      * @param string|array $args The query variables
     457     * @param string|array $args Optional. The query variables.
    434458     * @return WP_User_Query
    435459     */
    … …  
    442466
    443467    /**
    444      * Prepare the query variables
     468     * Prepare the query variables.
    445469     *
    446470     * @since 3.1.0
    447471     *
    448      * @param string|array $args The query variables
     472     * @param string|array $args Optional. The query variables.
    449473     */
    450474    function prepare_query( $query = array() ) {
    … …  
    654678
    655679    /**
    656      * Execute the query, with the current variables
     680     * Execute the query, with the current variables.
    657681     *
    658682     * @since 3.1.0
     683     *
     684     * @global wpdb $wpdb WordPress database object for queries.
    659685     */
    660686    function query() {
    … …  
    759785
    760786    /**
    761      * Return the list of users
     787     * Return the list of users.
    762788     *
    763789     * @since 3.1.0
    764790     * @access public
    765791     *
    766      * @return array
     792     * @return array Array of results.
    767793     */
    768794    function get_results() {
    … …  
    771797
    772798    /**
    773      * Return the total number of users for the current query
     799     * Return the total number of users for the current query.
    774800     *
    775801     * @since 3.1.0
    776802     * @access public
    777803     *
    778      * @return array
     804     * @return array Array of total users.
    779805     */
    780806    function get_total() {
    … …  
    787813 *
    788814 * @since 3.1.0
    789  * @uses $wpdb
     815 *
    790816 * @uses WP_User_Query See for default arguments and information.
    791817 *
    792  * @param array $args Optional.
     818 * @param array $args Optional. Array of arguments.
    793819 * @return array List of users.
    794820 */
    … …  
    808834 * @since 3.0.0
    809835 *
    810  * @param int $user_id User ID
    811  * @param bool $all Whether to retrieve all blogs, or only blogs that are not marked as deleted, archived, or spam.
    812  * @return array A list of the user's blogs. An empty array if the user doesn't exist or belongs to no blogs.
     836 * @global wpdb $wpdb WordPress database object for queries.
     837 *
     838 * @param int  $user_id User ID
     839 * @param bool $all     Whether to retrieve all blogs, or only blogs that are not
     840 *                      marked as deleted, archived, or spam.
     841 * @return array A list of the user's blogs. An empty array if the user doesn't exist
     842 *               or belongs to no blogs.
    813843 */
    814844function get_blogs_of_user( $user_id, $all = false ) {
    … …  
    11551185 *
    11561186 * @since 2.3.0
    1157  * @uses $wpdb WordPress database object for queries
    1158  *
    1159  * @param string|array $args Optional. Override defaults.
     1187 *
     1188 * @global wpdb $wpdb WordPress database object for queries.
     1189 *
     1190 * @todo Hash-notate arguments array.
     1191 *
     1192 * @param string|array $args Optional. Array of user arguments.
    11601193 * @return string|null Null on display. String of HTML content on retrieve.
    11611194 */
    … …  
    12401273 *
    12411274 * @since 2.3.0
    1242  * @uses apply_filters() Calls 'edit_$field' passing $value and $user_id if $context == 'edit'.
    1243  *  $field is prefixed with 'user_' if it isn't already.
    1244  * @uses apply_filters() Calls 'pre_$field' passing $value if $context == 'db'. $field is prefixed with
    1245  *  'user_' if it isn't already.
    1246  * @uses apply_filters() Calls '$field' passing $value, $user_id and $context if $context == anything
    1247  *  other than 'raw', 'edit' and 'db'. $field is prefixed with 'user_' if it isn't already.
    12481275 *
    12491276 * @param string $field The user Object field name.
    … …  
    12691296    if ( 'edit' == $context ) {
    12701297        if ( $prefixed ) {
     1298
    12711299            /** This filter is documented in wp-includes/post.php */
    12721300            $value = apply_filters( "edit_{$field}", $value, $user_id );
    12731301        } else {
     1302
    12741303            /**
    12751304             * Filter a user field value in the 'edit' context.
    … …  
    12951324            $value = apply_filters( "pre_{$field}", $value );
    12961325        } else {
     1326
    12971327            /**
    12981328             * Filter the value of a user field in the 'db' context.
    … …  
    13091339    } else {
    13101340        // Use display filters by default.
    1311         if ( $prefixed ){
     1341        if ( $prefixed ) {
     1342
    13121343            /** This filter is documented in wp-includes/post.php */
    13131344            $value = apply_filters( $field, $value, $user_id, $context );
    1314         }else{
     1345        } else {
     1346
    13151347            /**
    13161348             * Filter the value of a user field in a standard context.
    … …  
    13941426 *
    13951427 * @since 2.1.0
    1396  * @uses $wpdb
    13971428 *
    13981429 * @param string $email Email.
    … …  
    14611492 *
    14621493 * @since 2.0.0
    1463  * @uses $wpdb WordPress database layer.
    1464  * @uses apply_filters() Calls filters for most of the $userdata fields with the prefix 'pre_user'. See note above.
    1465  * @uses do_action() Calls 'profile_update' hook when updating giving the user's ID
    1466  * @uses do_action() Calls 'user_register' hook when creating a new user giving the user's ID
     1494 *
     1495 * @global wpdb $wpdb WordPress database object for queries.
     1496 *
     1497 * @todo Hash-notate arguments array.
    14671498 *
    14681499 * @param mixed $userdata An array of user data or a user object of type stdClass or WP_User.
    … …  
    14911522
    14921523    $user_login = sanitize_user($user_login, true);
     1524
    14931525    /**
    14941526     * Filter a username after it has been sanitized.
    … …  
    15131545    if ( empty($user_nicename) )
    15141546        $user_nicename = sanitize_title( $user_login );
     1547
    15151548    /**
    15161549     * Filter a user's nicename before the user is created or updated.
    … …  
    15241557    if ( empty($user_url) )
    15251558        $user_url = '';
     1559
    15261560    /**
    15271561     * Filter a user's URL before the user is created or updated.
    … …  
    15351569    if ( empty($user_email) )
    15361570        $user_email = '';
     1571
    15371572    /**
    15381573     * Filter a user's email before the user is created or updated.
    … …  
    15491584    if ( empty($nickname) )
    15501585        $nickname = $user_login;
     1586
    15511587    /**
    15521588     * Filter a user's nickname before the user is created or updated.
    … …  
    15601596    if ( empty($first_name) )
    15611597        $first_name = '';
     1598
    15621599    /**
    15631600     * Filter a user's first name before the user is created or updated.
    … …  
    15711608    if ( empty($last_name) )
    15721609        $last_name = '';
     1610
    15731611    /**
    15741612     * Filter a user's last name before the user is created or updated.
    … …  
    15931631            $display_name = $user_login;
    15941632    }
     1633
    15951634    /**
    15961635     * Filter a user's display name before the user is created or updated.
    … …  
    16041643    if ( empty($description) )
    16051644        $description = '';
     1645
    16061646    /**
    16071647     * Filter a user's description before the user is created or updated.
    … …  
    17041744 *
    17051745 * @since 2.0.0
    1706  * @see wp_insert_user() For what fields can be set in $userdata
     1746 *
     1747 * @see wp_insert_user() For what fields can be set in $userdata.
    17071748 *
    17081749 * @param mixed $userdata An array of user data or a user object of type stdClass or WP_User.
    … …  
    18421883 * but have a different WP_Error code so good user feedback can be provided.
    18431884 *
    1844  * @uses $wpdb WordPress Database object
     1885 * @global wpdb $wpdb WordPress database object for queries.
    18451886 *
    18461887 * @param string $key       Hash to validate sending user's password.
Note: See TracChangeset for help on using the changeset viewer.