Ticket #5509: pluggable.phpdoc.r6473.diff

File pluggable.phpdoc.r6473.diff, 15.5 kB (added by darkdragon, 7 months ago)

Incomplete documentation for pluggables.php based off of r6473

  • pluggable.php

    old new  
    11<?php 
     2/** 
     3 * These functions can be replaced via plugins.  They are loaded after 
     4 * plugins are loaded. 
     5 * 
     6 * @package WordPress 
     7 */ 
    28 
    3         /* These functions can be replaced via plugins.  They are loaded after 
    4          plugins are loaded. */ 
    5  
    69if ( !function_exists('set_current_user') ) : 
     10/** 
     11 * set_current_user() - {@internal Missing Short Description}} 
     12 * 
     13 * {@internal Missing Long Description 
     14 *              Documentation must describe why set_current_user() would be override 
     15 *              instead of wp_set_current_user(). There is a reason and must look for it. 
     16 *              If exists on the codex, then link to that instead. 
     17 * }} 
     18 * 
     19 * @since 2.0.1 
     20 * @see wp_set_current_user() An alias of wp_set_current_user() 
     21 * 
     22 * @param int $id 
     23 * @param string $name 
     24 * @return object returns wp_set_current_user() 
     25 */ 
    726function set_current_user($id, $name = '') { 
    827        return wp_set_current_user($id, $name); 
    928} 
    1029endif; 
    1130 
    1231if ( !function_exists('wp_set_current_user') ) : 
     32/** 
     33 * wp_set_current_user() - {@internal Missing Short Description}} 
     34 * 
     35 * {@internal Missing Long Description 
     36 *              Documentation must describe why wp_set_current_user() would be override 
     37 *              instead of set_current_user(). There is a reason and must look for it. 
     38 *              If exists on the codex, then link to that instead. 
     39 * }} 
     40 * 
     41 * @since  
     42 * @global object $current_user The current user object which holds the user data. 
     43 * 
     44 * @param int $id 
     45 * @param string $name 
     46 * @return object 
     47 */ 
    1348function wp_set_current_user($id, $name = '') { 
    1449        global $current_user; 
    1550 
    …… 
    2762endif; 
    2863 
    2964if ( !function_exists('wp_get_current_user') ) : 
     65/** 
     66 * wp_get_current_user() -  
     67 * 
     68 * @since  
     69 * 
     70 * @return unknown 
     71 */ 
    3072function wp_get_current_user() { 
    3173        global $current_user; 
    3274 
    …… 
    3779endif; 
    3880 
    3981if ( !function_exists('get_currentuserinfo') ) : 
     82/** 
     83 * get_currentuserinfo() -  
     84 * 
     85 * @since  
     86 * 
     87 * @return unknown 
     88 */ 
    4089function get_currentuserinfo() { 
    4190        global $current_user; 
    4291 
    …… 
    56105endif; 
    57106 
    58107if ( !function_exists('get_userdata') ) : 
     108/** 
     109 * get_userdata() -  
     110 * 
     111 * @since  
     112 * 
     113 * @param unknown_type $user_id 
     114 * @return unknown 
     115 */ 
    59116function get_userdata( $user_id ) { 
    60117        global $wpdb; 
    61118 
    …… 
    82139endif; 
    83140 
    84141if ( !function_exists('update_user_cache') ) : 
     142/** 
     143 * update_user_cache() -  
     144 * 
     145 * @since  
     146 * 
     147 * @return bool Only returns true 
     148 */ 
    85149function update_user_cache() { 
    86150        return true; 
    87151} 
    88152endif; 
    89153 
    90154if ( !function_exists('get_userdatabylogin') ) : 
     155/** 
     156 * get_userdatabylogin() -  
     157 * 
     158 * @since  
     159 * 
     160 * @param unknown_type $user_login 
     161 * @return unknown 
     162 */ 
    91163function get_userdatabylogin($user_login) { 
    92164        global $wpdb; 
    93165        $user_login = sanitize_user( $user_login ); 
    …… 
    118190endif; 
    119191 
    120192if ( !function_exists('get_user_by_email') ) : 
     193/** 
     194 * get_user_by_email() -  
     195 * 
     196 * @since  
     197 * 
     198 * @param unknown_type $email 
     199 * @return unknown 
     200 */ 
    121201function get_user_by_email($email) { 
    122202        global $wpdb; 
    123203 
    …… 
    145225endif; 
    146226 
    147227if ( !function_exists( 'wp_mail' ) ) : 
     228/** 
     229 * wp_mail() -  
     230 * 
     231 * @since  
     232 * 
     233 * @param unknown_type $to 
     234 * @param unknown_type $subject 
     235 * @param unknown_type $message 
     236 * @param unknown_type $headers 
     237 * @return unknown 
     238 */ 
    148239function wp_mail( $to, $subject, $message, $headers = '' ) { 
    149240        // Compact the input, apply the filters, and extract them back out 
    150241        extract( apply_filters( 'wp_mail', compact( 'to', 'subject', 'message', 'headers' ) ) ); 
    …… 
    291382endif; 
    292383 
    293384if ( !function_exists('wp_login') ) : 
     385/** 
     386 * wp_login() -  
     387 * 
     388 * @since  
     389 * 
     390 * @param unknown_type $username 
     391 * @param unknown_type $password 
     392 * @param unknown_type $deprecated 
     393 * @return unknown 
     394 */ 
    294395function wp_login($username, $password, $deprecated = false) { 
    295396        global $wpdb, $error; 
    296397 
    …… 
    325426endif; 
    326427 
    327428if ( !function_exists('wp_validate_auth_cookie') ) : 
     429/** 
     430 * wp_validate_auth_cookie() -  
     431 * 
     432 * @since  
     433 * 
     434 * @param unknown_type $cookie 
     435 * @return unknown 
     436 */ 
    328437function wp_validate_auth_cookie($cookie = '') { 
    329438        if ( empty($cookie) ) { 
    330439                if ( empty($_COOKIE[AUTH_COOKIE]) ) 
    …… 
    358467endif; 
    359468 
    360469if ( !function_exists('wp_set_auth_cookie') ) : 
     470/** 
     471 * wp_set_auth_cookie() -  
     472 * 
     473 * @since  
     474 * 
     475 * @param unknown_type $user_id 
     476 * @param unknown_type $remember 
     477 */ 
    361478function wp_set_auth_cookie($user_id, $remember = false) { 
    362479        $user = get_userdata($user_id); 
    363480 
    …… 
    380497endif; 
    381498 
    382499if ( !function_exists('wp_clear_auth_cookie') ) : 
     500/** 
     501 * wp_clear_auth_cookie() -  
     502 * 
     503 * @since  
     504 * 
     505 */ 
    383506function wp_clear_auth_cookie() { 
    384507        setcookie(AUTH_COOKIE, ' ', time() - 31536000, COOKIEPATH, COOKIE_DOMAIN); 
    385508        setcookie(AUTH_COOKIE, ' ', time() - 31536000, SITECOOKIEPATH, COOKIE_DOMAIN); 
    …… 
    393516endif; 
    394517 
    395518if ( !function_exists('is_user_logged_in') ) : 
     519/** 
     520 * is_user_logged_in() -  
     521 * 
     522 * @since  
     523 * 
     524 * @return bool 
     525 */ 
    396526function is_user_logged_in() { 
    397527        $user = wp_get_current_user(); 
    398528 
    …… 
    404534endif; 
    405535 
    406536if ( !function_exists('auth_redirect') ) : 
     537/** 
     538 * auth_redirect() -  
     539 * 
     540 * @since  
     541 * 
     542 */ 
    407543function auth_redirect() { 
    408544        // Checks if a user is logged in, if not redirects them to the login page 
    409545        if ( (!empty($_COOKIE[AUTH_COOKIE]) && 
    …… 
    418554endif; 
    419555 
    420556if ( !function_exists('check_admin_referer') ) : 
     557/** 
     558 * check_admin_referer() -  
     559 * 
     560 * @param unknown_type $action 
     561 */ 
    421562function check_admin_referer($action = -1) { 
    422563        $adminurl = strtolower(get_option('siteurl')).'/wp-admin'; 
    423564        $referer = strtolower(wp_get_referer()); 
    …… 
    430571}endif; 
    431572 
    432573if ( !function_exists('check_ajax_referer') ) : 
     574/** 
     575 * check_ajax_referer() -  
     576 * 
     577 * @since  
     578 * 
     579 * @param unknown_type $action 
     580 */ 
    433581function check_ajax_referer( $action = -1 ) { 
    434582        $nonce = $_REQUEST['_ajax_nonce'] ? $_REQUEST['_ajax_nonce'] : $_REQUEST['_wpnonce']; 
    435583        if ( !wp_verify_nonce( $nonce, $action ) ) { 
    …… 
    462610// Cookie safe redirect.  Works around IIS Set-Cookie bug. 
    463611// http://support.microsoft.com/kb/q176113/ 
    464612if ( !function_exists('wp_redirect') ) : 
     613/** 
     614 * wp_redirect() -  
     615 * 
     616 * @since  
     617 * 
     618 * @param unknown_type $location 
     619 * @param unknown_type $status 
     620 * @return unknown 
     621 */ 
    465622function wp_redirect($location, $status = 302) { 
    466623        global $is_IIS; 
    467624 
    …… 
    484641 
    485642if ( !function_exists('wp_sanitize_redirect') ) : 
    486643/** 
    487  * sanitizes a URL for use in a redirect 
     644 * wp_sanitize_redirect() - Sanitizes a URL for use in a redirect 
     645 * 
     646 * @since  
     647 * 
    488648 * @return string redirect-sanitized URL 
    489649 **/ 
    490650function wp_sanitize_redirect($location) { 
    …… 
    509669 
    510670if ( !function_exists('wp_safe_redirect') ) : 
    511671/** 
    512  * performs a safe (local) redirect, using wp_redirect() 
     672 * wp_safe_redirect() - Performs a safe (local) redirect, using wp_redirect() 
     673 * 
     674 * @since 2.3 
     675 * 
    513676 * @return void 
    514677 **/ 
    515678function wp_safe_redirect($location, $status = 302) { 
    …… 
    534697endif; 
    535698 
    536699if ( ! function_exists('wp_notify_postauthor') ) : 
     700/** 
     701 * wp_notify_postauthor() - Notify an author of a comment/trackback/pingback to one of their posts 
     702 * 
     703 * @since 1.0.1 
     704 * 
     705 * @param int $comment_id Comment ID 
     706 * @param string $comment_type Optional. The comment type either 'comment' (default), 'trackback', or 'pingback' 
     707 * @return bool False if user email does not exist. True on completion. 
     708 */ 
    537709function wp_notify_postauthor($comment_id, $comment_type='') { 
    538710        $comment = get_comment($comment_id); 
    539711        $post    = get_post($comment->comment_post_ID); 
    …… 
    603775} 
    604776endif; 
    605777 
    606 /* wp_notify_moderator 
    607    notifies the moderator of the blog (usually the admin) 
    608    about a new comment that waits for approval 
    609    always returns true 
     778if ( !function_exists('wp_notify_moderator') ) : 
     779/** 
     780 * wp_notify_moderator() - Notifies the moderator of the blog about a new comment that is awaiting approval 
     781 * 
     782 * @since 1.0.1 
     783 * @uses $wpdb 
     784 * 
     785 * @param int $comment_id Comment ID 
     786 * @return bool Always returns true 
    610787 */ 
    611 if ( !function_exists('wp_notify_moderator') ) : 
    612788function wp_notify_moderator($comment_id) { 
    613789        global $wpdb; 
    614790 
    …… 
    648824endif; 
    649825 
    650826if ( !function_exists('wp_new_user_notification') ) : 
     827/** 
     828 * wp_new_user_notification() - Notify the blog admin of a new user, normally via email 
     829 * 
     830 * @since 2.0 
     831 * 
     832 * @param int $user_id User ID 
     833 * @param string $plaintext_pass Optional. The user's plaintext password 
     834 */ 
    651835function wp_new_user_notification($user_id, $plaintext_pass = '') { 
    652836        $user = new WP_User($user_id); 
    653837 
    …… 
    673857endif; 
    674858 
    675859if ( !function_exists('wp_verify_nonce') ) : 
     860/** 
     861 * wp_verify_nonce() - Verify that correct nonce was used with time limit 
     862 * 
     863 * The user is given an amount of time to use the token, so therefore, since 
     864 * the UID and $action remain the same, the independent variable is the time. 
     865 * 
     866 * @since 2.0.4 
     867 * 
     868 * @param string $nonce 
     869 * @param string|int $action Should give context to what is taking place and be the same when nonce was created. 
     870 * @return bool Whether the nonce check passed or failed. 
     871 */ 
    676872function wp_verify_nonce($nonce, $action = -1) { 
    677873        $user = wp_get_current_user(); 
    678874        $uid = (int) $user->id; 
    …… 
    687883endif; 
    688884 
    689885if ( !function_exists('wp_create_nonce') ) : 
     886/** 
     887 * wp_create_nonce() - Creates a random, one use token 
     888 * 
     889 * @since 2.0.4 
     890 * 
     891 * @param string|int $action Scalar value to add context to the nonce. 
     892 * @return string The one use form token 
     893 */ 
    690894function wp_create_nonce($action = -1) { 
    691895        $user = wp_get_current_user(); 
    692896        $uid = (int) $user->id; 
    …… 
    698902endif; 
    699903 
    700904if ( !function_exists('wp_salt') ) : 
     905/** 
     906 * wp_salt() - Get salt to add to hashes to help prevent attacks 
     907 * 
     908 * You can set the salt by defining two areas. One is in the database and 
     909 * the other is in your wp-config.php file. The database location is defined 
     910 * in the option named 'secret', but most likely will not need to be changed. 
     911 * 
     912 * The second, located in wp-config.php, is a constant named 'SECRET_KEY', but 
     913 * is not required. If the constant is not defined then the database constants 
     914 * will be used, since they are most likely given to be unique. However, given 
     915 * that the salt will be added to the password and can be seen, the constant 
     916 * is recommended to be set manually. 
     917 * 
     918 * <code> 
     919 * define('SECRET_KEY', 'mAry1HadA15|\/|b17w55w1t3asSn09w'); 
     920 * </code> 
     921 * 
     922 * Attention: Do not use above example! 
     923 * 
     924 * Salting passwords helps against tools which has stored hashed values 
     925 * of common dictionary strings. The added values makes it harder to crack 
     926 * if given salt string is not weak. 
     927 * 
     928 * Salting only helps if the string is not predictable and should be 
     929 * made up of various characters. Think of the salt as a password for 
     930 * securing your passwords, but common among all of your passwords. 
     931 * Therefore the salt should be as long as possible as as difficult as 
     932 * possible, because you will not have to remember it. 
     933 * 
     934 * @since 2.4 
     935 * 
     936 * @return unknown 
     937 */ 
    701938function wp_salt() { 
    702939 
    703940        if ( defined('SECRET_KEY') && '' != SECRET_KEY ) 
    …… 
    714951endif; 
    715952 
    716953if ( !function_exists('wp_hash') ) : 
     954/** 
     955 * wp_hash() - Get hash of given string 
     956 * 
     957 * @since 2.0.4 
     958 * @uses wp_salt() Get WordPress salt 
     959 * 
     960 * @param string $data Plain text to hash 
     961 * @return string Hash of $data 
     962 */ 
    717963function wp_hash($data) { 
    718964        $salt = wp_salt(); 
    719965 
    …… 
    726972endif; 
    727973 
    728974if ( !function_exists('wp_hash_password') ) : 
     975/** 
     976 * wp_hash_password() - Create a hash (encrypt) of a plain text password 
     977 * 
     978 * For integration with other applications, this function can be 
     979 * overwritten to instead use the other package password checking 
     980 * algorithm. 
     981 * 
     982 * @since 2.4 
     983 * @global object $wp_hasher PHPass object 
     984 * @uses PasswordHash::HashPassword 
     985 * 
     986 * @param string $password Plain text user password to hash 
     987 * @return string The hash string of the password 
     988 */ 
    729989function wp_hash_password($password) { 
    730990        global $wp_hasher; 
    731991 
    …… 
    7401000endif; 
    7411001 
    7421002if ( !function_exists('wp_check_password') ) : 
     1003/** 
     1004 * wp_check_password() - Checks the plaintext password against the encrypted Password 
     1005 * 
     1006 * Maintains compatibility between old version and the new cookie 
     1007 * authentication protocol using PHPass library. The $hash parameter 
     1008 * is the encrypted password and the function compares the plain text 
     1009 * password when encypted similarly against the already encrypted 
     1010 * password to see if they match. 
     1011 * 
     1012 * For integration with other applications, this function can be 
     1013 * overwritten to instead use the other package password checking 
     1014 * algorithm. 
     1015 * 
     1016 * @since 2.4 
     1017 * @global object $wp_hasher PHPass object used for checking the password 
     1018 *      against the $hash + $password 
     1019 * @uses PasswordHash::CheckPassword 
     1020 * 
     1021 * @param string $password 
     1022 * @param string $hash 
     1023 * @return bool False, if the $password does not match the hashed password 
     1024 */ 
    7431025function wp_check_password($password, $hash) { 
    7441026        global $wp_hasher; 
    7451027 
    …… 
    7601042 
    7611043if ( !function_exists('wp_generate_password') ) : 
    7621044/** 
    763  * Generates a random password drawn from the defined set of characters 
    764  * @return string the password 
     1045 * wp_generate_password() - Generates a random password drawn from the defined set of characters 
     1046 * 
     1047 * @since 2.4 
     1048 * 
     1049 * @return string The random password 
    7651050 **/ 
    7661051function wp_generate_password() { 
    7671052        $chars = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"; 
    …… 
    7741059endif; 
    7751060 
    7761061if ( !function_exists('wp_set_password') ) : 
     1062/** 
     1063 * wp_set_password() - Updates the user's password with a new encrypted one 
     1064 * 
     1065 * For integration with other applications, this function can be 
     1066 * overwritten to instead use the other package password checking 
     1067 * algorithm. 
     1068 * 
     1069 * @since 2.4 
     1070 * @uses $wpdb WordPress database object for queries 
     1071 * @uses wp_hash_password() Used to encrypt the user's password before passing to the database 
     1072 * 
     1073 * @param string $password The plaintext new user password 
     1074 * @param int $user_id User ID 
     1075 */ 
    7771076function wp_set_password( $password, $user_id ) { 
    7781077        global $wpdb; 
    7791078 
    …… 
    7841083} 
    7851084endif; 
    7861085 
    787 // Deprecated. Use wp_set_auth_cookie() 
    7881086if ( !function_exists('wp_setcookie') ) : 
     1087/** 
     1088 * wp_setcookie() - Sets a cookie for a user who just logged in 
     1089 * 
     1090 * @since 1.5 
     1091 * @deprecated Use wp_set_auth_cookie() 
     1092 * @see wp_set_auth_cookie() 
     1093 * 
     1094 * @param string  $username The user's username 
     1095 * @param string  $password Optional. The user's password 
     1096 * @param bool $already_md5 Optional. Whether the password has already been through MD5 
     1097 * @param string $home Optional. Will be used instead of COOKIEPATH if set 
     1098 * @param string $siteurl Optional. Will be used instead of SITECOOKIEPATH if set 
     1099 * @param bool $remember Optional. Remember that the user is logged in 
     1100 */ 
    7891101function wp_setcookie($username, $password = '', $already_md5 = false, $home = '', $siteurl = '', $remember = false) { 
    7901102        $user = get_userdatabylogin($username); 
    7911103        wp_set_auth_cookie($user->ID, $remember); 
    7921104} 
    7931105endif; 
    7941106 
    795 // Deprecated. Use wp_clear_auth_cookie() 
    7961107if ( !function_exists('wp_clearcookie') ) : 
     1108/** 
     1109 * wp_clearcookie() - Clears the authentication cookie, logging the user out 
     1110 * 
     1111 * @since 1.5 
     1112 * @deprecated Use wp_clear_auth_cookie() 
     1113 * @see wp_clear_auth_cookie() 
     1114 */ 
    7971115function wp_clearcookie() { 
    7981116        wp_clear_auth_cookie(); 
    7991117} 
    8001118endif; 
    8011119 
    802 // Deprecated.  No alternative. 
    8031120if ( !function_exists('wp_get_cookie_login') ): 
     1121/** 
     1122 * wp_get_cookie_login() - {@internal Missing Short Description}} 
     1123 * 
     1124 * @since 2.0.4 
     1125 * @deprecated No alternative 
     1126 * 
     1127 * @return bool Always returns false 
     1128 */ 
    8041129function wp_get_cookie_login() { 
    8051130        return false; 
    8061131}