Ticket #5509: pluggable.phpdoc.r6636.diff

File pluggable.phpdoc.r6636.diff, 12.4 kB (added by darkdragon, 6 months ago)

Completed phpdoc for pluggable.php based on r6636

  • pluggable.php

    old new  
    2525endif; 
    2626 
    2727if ( !function_exists('wp_set_current_user') ) : 
     28/** 
     29 * wp_set_current_user() - Changes the current user by ID or name 
     30 * 
     31 * Set $id to null and specify a name if you do not know a user's ID 
     32 * 
     33 * Some WordPress functionality is based on the current user and 
     34 * not based on the signed in user. Therefore, it opens the ability 
     35 * to edit and perform actions on users who aren't signed in. 
     36 * 
     37 * @since 2.0.4 
     38 * @global object $current_user The current user object which holds the user data. 
     39 * @uses do_action() Calls 'set_current_user' hook after setting the current user. 
     40 * 
     41 * @param int $id User ID 
     42 * @param string $name User's username 
     43 * @return WP_User Current user User object 
     44 */ 
    2845function wp_set_current_user($id, $name = '') { 
    2946        global $current_user; 
    3047 
    …… 
    4259endif; 
    4360 
    4461if ( !function_exists('wp_get_current_user') ) : 
     62/** 
     63 * wp_get_current_user() - Retrieve the current user object 
     64 * 
     65 * @since 2.0.4 
     66 * 
     67 * @return WP_User Current user WP_User object 
     68 */ 
    4569function wp_get_current_user() { 
    4670        global $current_user; 
    4771 
    …… 
    5579/** 
    5680 * get_currentuserinfo() - Populate global variables with information about the currently logged in user 
    5781 * 
    58  * {@internal Missing Long Description}} 
     82 * Will set the current user, if the current user is not set. The current 
     83 * user will be set to the logged in person. If no user is logged in, then 
     84 * it will set the current user to 0, which is invalid and won't have any 
     85 * permissions. 
    5986 * 
    6087 * @since 0.71 
     88 * @uses $current_user Checks if the current user is set 
     89 * @uses wp_validate_auth_cookie() Retrieves current logged in user. 
    6190 * 
    62  * @return unknown {@internal Missing Description}} 
     91 * @return bool|null False on XMLRPC Request and invalid auth cookie. Null when current user set 
    6392 */ 
    6493function get_currentuserinfo() { 
    6594        global $current_user; 
    …… 
    81110 
    82111if ( !function_exists('get_userdata') ) : 
    83112/** 
    84  * get_userdata() - Get an object containing data about a user 
     113 * get_userdata() - Retrieve user info by user ID 
    85114 * 
    86  * {@internal Missing Long Description}} 
    87  * 
    88115 * @since 0.71 
    89116 * 
    90  * @param unknown_type $user_id {@internal Missing Description}} 
    91  * @return unknown {@internal Missing Description}} 
     117 * @param int $user_id User ID 
     118 * @return bool|object False on failure, User DB row object 
    92119 */ 
    93120function get_userdata( $user_id ) { 
    94121        global $wpdb; 
    …… 
    132159 
    133160if ( !function_exists('get_userdatabylogin') ) : 
    134161/** 
    135  * get_userdatabylogin() - Grabs some info about a user based on their login name 
     162 * get_userdatabylogin() - Retrieve user info by login name 
    136163 * 
    137  * {@internal Missing Long Description}} 
    138  * 
    139164 * @since 0.71 
    140165 * 
    141  * @param string $user_login {@internal Missing Description}} 
    142  * @return unknown {@internal Missing Description}} 
     166 * @param string $user_login User's username 
     167 * @return bool|object False on failure, User DB row object 
    143168 */ 
    144169function get_userdatabylogin($user_login) { 
    145170        global $wpdb; 
    …… 
    171196endif; 
    172197 
    173198if ( !function_exists('get_user_by_email') ) : 
     199/** 
     200 * get_user_by_email() - Retrieve user info by email 
     201 * 
     202 * @since 2.5 
     203 * 
     204 * @param string $email User's email address 
     205 * @return bool|object False on failure, User DB row object 
     206 */ 
    174207function get_user_by_email($email) { 
    175208        global $wpdb; 
    176209 
    …… 
    201234/** 
    202235 * wp_mail() - Function to send mail, similar to PHP's mail 
    203236 * 
    204  * {@internal Missing Long Description}} 
     237 * A true return value does not automatically mean that the 
     238 * user received the email successfully. It just only means 
     239 * that the method used was able to process the request 
     240 * without any errors. 
    205241 * 
     242 * Using the two 'wp_mail_from' and 'wp_mail_from_name' hooks 
     243 * allow from creating a from address like 'Name <email@address.com>' 
     244 * when both are set. If just 'wp_mail_from' is set, then just 
     245 * the email address will be used with no name. 
     246 * 
     247 * The default content type is 'text/plain' which does not 
     248 * allow using HTML. However, you can set the content type 
     249 * of the email by using the 'wp_mail_content_type' filter. 
     250 * 
     251 * The default charset is based on the charset used on the 
     252 * blog. The charset can be set using the 'wp_mail_charset' 
     253 * filter. 
     254 * 
    206255 * @since 1.2.1 
     256 * @uses apply_filters() Calls 'wp_mail' hook on an array of all of the parameters. 
     257 * @uses apply_filters() Calls 'wp_mail_from' hook to get the from email address. 
     258 * @uses apply_filters() Calls 'wp_mail_from_name' hook to get the from address name. 
     259 * @uses apply_filters() Calls 'wp_mail_content_type' hook to get the email content type. 
     260 * @uses apply_filters() Calls 'wp_mail_charset' hook to get the email charset 
     261 * @uses do_action_ref_array() Calls 'phpmailer_init' hook on the reference to 
     262 *              phpmailer object. 
     263 * @uses PHPMailer 
     264 * @ 
    207265 * 
    208  * @param string $to {@internal Missing Description}} 
    209  * @param string $subject {@internal Missing Description}} 
    210  * @param string $message {@internal Missing Description}} 
    211  * @param string $headers {@internal Missing Description}} 
    212  * @return unknown {@internal Missing Description}} 
     266 * @param string $to Email address to send message 
     267 * @param string $subject Email subject 
     268 * @param string $message Message contents 
     269 * @param string|array $headers Optional. Additional headers. 
     270 * @return bool Whether the email contents were sent successfully. 
    213271 */ 
    214272function wp_mail( $to, $subject, $message, $headers = '' ) { 
    215273        // Compact the input, apply the filters, and extract them back out 
    …… 
    359417/** 
    360418 * wp_login() - Checks a users login information and logs them in if it checks out 
    361419 * 
    362  * {@internal Missing Long Description}} 
     420 * Use the global $error to get the reason why the login failed. 
     421 * If the username is blank, no error will be set, so assume 
     422 * blank username on that case. 
    363423 * 
     424 * Plugins extending this function should also provide the global 
     425 * $error and set what the error is, so that those checking the 
     426 * global for why there was a failure can utilize it later. 
     427 * 
    364428 * @since 1.2.2 
     429 * @global string $error Error when false is returned 
    365430 * 
    366  * @param string $username {@internal Missing Description}} 
    367  * @param string $password {@internal Missing Description}} 
    368  * @param bool $deprecated {@internal Missing Description}} 
    369  * @return unknown {@internal Missing Description}} 
     431 * @param string $username User's username 
     432 * @param string $password User's password 
     433 * @param bool $deprecated Not used 
     434 * @return bool False on login failure, true on successful check 
    370435 */ 
    371436function wp_login($username, $password, $deprecated = '') { 
    372437        global $error; 
    …… 
    402467endif; 
    403468 
    404469if ( !function_exists('wp_validate_auth_cookie') ) : 
     470/** 
     471 * wp_validate_auth_cookie() - Validates authentication cookie 
     472 * 
     473 * The checks include making sure that the authentication cookie 
     474 * is set and pulling in the contents (if $cookie is not used). 
     475 * 
     476 * Makes sure the cookie is not expired. Verifies the hash in 
     477 * cookie is what is should be and compares the two. 
     478 * 
     479 * @since 2.5 
     480 * 
     481 * @param string $cookie Optional. If used, will validate contents instead of cookie's 
     482 * @return bool|int False if invalid cookie, User ID if valid. 
     483 */ 
    405484function wp_validate_auth_cookie($cookie = '') { 
    406485        if ( empty($cookie) ) { 
    407486                if ( empty($_COOKIE[AUTH_COOKIE]) ) 
    …… 
    435514endif; 
    436515 
    437516if ( !function_exists('wp_generate_auth_cookie') ) : 
     517/** 
     518 * wp_generate_auth_cookie() - Generate authentication cookie contents 
     519 * 
     520 * @since 2.5 
     521 * @uses apply_filters() Calls 'auth_cookie' hook on $cookie contents, User ID 
     522 *              and expiration of cookie. 
     523 * 
     524 * @param int $user_id User ID 
     525 * @param int $expiration Cookie expiration in seconds 
     526 * @return string Authentication cookie contents 
     527 */ 
    438528function wp_generate_auth_cookie($user_id, $expiration) { 
    439529        $user = get_userdata($user_id); 
    440530 
    …… 
    448538endif; 
    449539 
    450540if ( !function_exists('wp_set_auth_cookie') ) : 
     541/** 
     542 * wp_set_auth_cookie() - Sets the authentication cookies based User ID 
     543 * 
     544 * The $remember parameter increases the time that the cookie will 
     545 * be kept. The default the cookie is kept without remembering is 
     546 * two days. When $remember is set, the cookies will be kept for 
     547 * 14 days or two weeks. 
     548 * 
     549 * @since 2.5 
     550 * 
     551 * @param int $user_id User ID 
     552 * @param bool $remember Whether to remember the user or not 
     553 */ 
    451554function wp_set_auth_cookie($user_id, $remember = false) { 
    452555        if ( $remember ) { 
    453556                $expiration = $expire = time() + 1209600; 
    …… 
    467570endif; 
    468571 
    469572if ( !function_exists('wp_clear_auth_cookie') ) : 
     573/** 
     574 * wp_clear_auth_cookie() - Deletes all of the cookies associated with authentication 
     575 * 
     576 * @since 2.5 
     577 */ 
    470578function wp_clear_auth_cookie() { 
    471579        setcookie(AUTH_COOKIE, ' ', time() - 31536000, COOKIEPATH, COOKIE_DOMAIN); 
    472580        setcookie(AUTH_COOKIE, ' ', time() - 31536000, SITECOOKIEPATH, COOKIE_DOMAIN); 
    …… 
    483591/** 
    484592 * is_user_logged_in() - Checks if the current visitor is a logged in user 
    485593 * 
    486  * {@internal Missing Long Description}} 
    487  * 
    488594 * @since 2.0.0 
    489595 * 
    490  * @return bool {@internal Missing Description}} 
     596 * @return bool True if user is logged in, false if not logged in. 
    491597 */ 
    492598function is_user_logged_in() { 
    493599        $user = wp_get_current_user(); 
    …… 
    503609/** 
    504610 * auth_redirect() - Checks if a user is logged in, if not it redirects them to the login page 
    505611 * 
    506  * {@internal Missing Long Description}} 
    507  * 
    508612 * @since 1.5 
    509613 */ 
    510614function auth_redirect() { 
    511615        // Checks if a user is logged in, if not redirects them to the login page 
    512616        if ( (!empty($_COOKIE[AUTH_COOKIE]) && 
    513617                                !wp_validate_auth_cookie($_COOKIE[AUTH_COOKIE])) || 
    514                          (empty($_COOKIE[AUTH_COOKIE])) ) { 
     618                        (empty($_COOKIE[AUTH_COOKIE])) ) { 
    515619                nocache_headers(); 
    516620 
    517621                wp_redirect(get_option('siteurl') . '/wp-login.php?redirect_to=' . urlencode($_SERVER['REQUEST_URI'])); 
    …… 
    524628/** 
    525629 * check_admin_referer() - Makes sure that a user was referred from another admin page, to avoid security exploits 
    526630 * 
    527  * {@internal Missing Long Description}} 
    528  * 
    529631 * @since 1.2.0 
     632 * @uses do_action() Calls 'check_admin_referer' on $action. 
    530633 * 
    531  * @param unknown_type $action {@internal Missing Description}} 
     634 * @param string $action Action nonce 
    532635 */ 
    533636function check_admin_referer($action = -1) { 
    534637        $adminurl = strtolower(get_option('siteurl')).'/wp-admin'; 
    …… 
    542645}endif; 
    543646 
    544647if ( !function_exists('check_ajax_referer') ) : 
     648/** 
     649 * check_ajax_referer() - Verifies the AJAX request to prevent processing requests external of the blog. 
     650 * 
     651 * @since 2.0.4 
     652 * 
     653 * @param string $action Action nonce 
     654 */ 
    545655function check_ajax_referer( $action = -1 ) { 
    546656        $nonce = $_REQUEST['_ajax_nonce'] ? $_REQUEST['_ajax_nonce'] : $_REQUEST['_wpnonce']; 
    547657        if ( !wp_verify_nonce( $nonce, $action ) ) { 
    …… 
    563673 
    564674                if ( ! $user_id = wp_validate_auth_cookie( $auth_cookie ) ) 
    565675                        die('-1'); 
    566          
     676 
    567677                if ( $current_id != $user_id ) 
    568678                        die('-1'); 
    569679        } 
    …… 
    577687 * 
    578688 * @link http://support.microsoft.com/kb/q176113/ 
    579689 * @since 1.5.1 
     690 * @uses apply_filters() Calls 'wp_redirect' hook on $location and $status. 
    580691 * 
    581  * @param string $location {@internal Missing Description}} 
    582  * @param int $status {@internal Missing Description}} 
    583  * @return unknown {@internal Missing Description}} 
     692 * @param string $location The path to redirect to 
     693 * @param int $status Status code to use 
     694 * @return bool False if $location is not set 
    584695 */ 
    585696function wp_redirect($location, $status = 302) { 
    586697        global $is_IIS; 
    …… 
    634745/** 
    635746 * wp_safe_redirect() - Performs a safe (local) redirect, using wp_redirect() 
    636747 * 
     748 * Checks whether the $location is using an allowed host, if it has an absolute 
     749 * path. A plugin can therefore set or remove allowed host(s) to or from the list. 
     750 * 
     751 * If the host is not allowed, then the redirect is to wp-admin on the siteurl 
     752 * instead. This prevents malicious redirects which redirect to another host, but 
     753 * only used in a few places. 
     754 * 
    637755 * @since 2.3 
     756 * @uses apply_filters() Calls 'allowed_redirect_hosts' on an array containing  
     757 *              WordPress host string and $location host string. 
    638758 * 
    639759 * @return void Does not return anything 
    640760 **/ 
    …… 
    663783/** 
    664784 * wp_notify_postauthor() - Notify an author of a comment/trackback/pingback to one of their posts 
    665785 * 
    666  * @since 1.0 
     786 * @since 1.0.0 
    667787 * 
    668788 * @param int $comment_id Comment ID 
    669789 * @param string $comment_type Optional. The comment type either 'comment' (default), 'trackback', or 'pingback'