Changeset 6600

Show
Ignore:
Timestamp:
01/11/08 20:51:39 (6 months ago)
Author:
ryan
Message:

phpdoc for pluggable from darkdragon. fixes #5509

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • trunk/wp-includes/pluggable.php

    r6599 r6600  
    11<?php 
    2  
    3     /* These functions can be replaced via plugins.  They are loaded after 
    4      plugins are loaded. */ 
     2/** 
     3 * These functions can be replaced via plugins. They are loaded after 
     4 * plugins are loaded. 
     5 * 
     6 * @package WordPress 
     7 */ 
    58 
    69if ( !function_exists('set_current_user') ) : 
     10/** 
     11 * set_current_user() - Populates global user information for any user 
     12 * 
     13 * Set $id to null and specify a name if you do not know a user's ID 
     14 * 
     15 * @since 2.0.1 
     16 * @see wp_set_current_user() An alias of wp_set_current_user() 
     17 * 
     18 * @param int|null $id User ID. 
     19 * @param string $name Optional. The user's username 
     20 * @return object returns wp_set_current_user() 
     21 */ 
    722function set_current_user($id, $name = '') { 
    823    return wp_set_current_user($id, $name); 
    …… 
    3853 
    3954if ( !function_exists('get_currentuserinfo') ) : 
     55/** 
     56 * get_currentuserinfo() - Populate global variables with information about the currently logged in user 
     57 * 
     58 * {@internal Missing Long Description}} 
     59 * 
     60 * @since 0.71 
     61 * 
     62 * @return unknown {@internal Missing Description}} 
     63 */ 
    4064function get_currentuserinfo() { 
    4165    global $current_user; 
    …… 
    5781 
    5882if ( !function_exists('get_userdata') ) : 
     83/** 
     84 * get_userdata() - Get an object containing data about a user 
     85 * 
     86 * {@internal Missing Long Description}} 
     87 * 
     88 * @since 0.71 
     89 * 
     90 * @param unknown_type $user_id {@internal Missing Description}} 
     91 * @return unknown {@internal Missing Description}} 
     92 */ 
    5993function get_userdata( $user_id ) { 
    6094    global $wpdb; 
    …… 
    83117 
    84118if ( !function_exists('update_user_cache') ) : 
     119/** 
     120 * update_user_cache() - Updates a users cache when overridden by a plugin 
     121 * 
     122 * Core function does nothing. 
     123 * 
     124 * @since 1.5 
     125 * 
     126 * @return bool Only returns true 
     127 */ 
    85128function update_user_cache() { 
    86129    return true; 
    …… 
    89132 
    90133if ( !function_exists('get_userdatabylogin') ) : 
     134/** 
     135 * get_userdatabylogin() - Grabs some info about a user based on their login name 
     136 * 
     137 * {@internal Missing Long Description}} 
     138 * 
     139 * @since 0.71 
     140 * 
     141 * @param string $user_login {@internal Missing Description}} 
     142 * @return unknown {@internal Missing Description}} 
     143 */ 
    91144function get_userdatabylogin($user_login) { 
    92145    global $wpdb; 
    …… 
    146199 
    147200if ( !function_exists( 'wp_mail' ) ) : 
     201/** 
     202 * wp_mail() - Function to send mail, similar to PHP's mail 
     203 * 
     204 * {@internal Missing Long Description}} 
     205 * 
     206 * @since 1.2.1 
     207 * 
     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}} 
     213 */ 
    148214function wp_mail( $to, $subject, $message, $headers = '' ) { 
    149215    // Compact the input, apply the filters, and extract them back out 
    …… 
    291357 
    292358if ( !function_exists('wp_login') ) : 
     359/** 
     360 * wp_login() - Checks a users login information and logs them in if it checks out 
     361 * 
     362 * {@internal Missing Long Description}} 
     363 * 
     364 * @since 1.2.2 
     365 * 
     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}} 
     370 */ 
    293371function wp_login($username, $password, $deprecated = '') { 
    294372    global $error; 
    …… 
    403481 
    404482if ( !function_exists('is_user_logged_in') ) : 
     483/** 
     484 * is_user_logged_in() - Checks if the current visitor is a logged in user 
     485 * 
     486 * {@internal Missing Long Description}} 
     487 * 
     488 * @since 2.0.0 
     489 * 
     490 * @return bool {@internal Missing Description}} 
     491 */ 
    405492function is_user_logged_in() { 
    406493    $user = wp_get_current_user(); 
    …… 
    414501 
    415502if ( !function_exists('auth_redirect') ) : 
     503/** 
     504 * auth_redirect() - Checks if a user is logged in, if not it redirects them to the login page 
     505 * 
     506 * {@internal Missing Long Description}} 
     507 * 
     508 * @since 1.5 
     509 */ 
    416510function auth_redirect() { 
    417511    // Checks if a user is logged in, if not redirects them to the login page 
    …… 
    428522 
    429523if ( !function_exists('check_admin_referer') ) : 
     524/** 
     525 * check_admin_referer() - Makes sure that a user was referred from another admin page, to avoid security exploits 
     526 * 
     527 * {@internal Missing Long Description}} 
     528 * 
     529 * @since 1.2.0 
     530 * 
     531 * @param unknown_type $action {@internal Missing Description}} 
     532 */ 
    430533function check_admin_referer($action = -1) { 
    431534    $adminurl = strtolower(get_option('siteurl')).'/wp-admin'; 
    …… 
    469572endif; 
    470573 
    471 // Cookie safe redirect.  Works around IIS Set-Cookie bug. 
    472 // http://support.microsoft.com/kb/q176113/ 
    473574if ( !function_exists('wp_redirect') ) : 
     575/** 
     576 * wp_redirect() - Redirects to another page, with a workaround for the IIS Set-Cookie bug 
     577 * 
     578 * @link http://support.microsoft.com/kb/q176113/ 
     579 * @since 1.5.1 
     580 * 
     581 * @param string $location {@internal Missing Description}} 
     582 * @param int $status {@internal Missing Description}} 
     583 * @return unknown {@internal Missing Description}} 
     584 */ 
    474585function wp_redirect($location, $status = 302) { 
    475586    global $is_IIS; 
    …… 
    494605if ( !function_exists('wp_sanitize_redirect') ) : 
    495606/** 
    496  * sanitizes a URL for use in a redirect 
     607 * wp_sanitize_redirect() - Sanitizes a URL for use in a redirect 
     608 * 
     609 * @since 2.3 
     610 * 
    497611 * @return string redirect-sanitized URL 
    498612 **/ 
    …… 
    519633if ( !function_exists('wp_safe_redirect') ) : 
    520634/** 
    521  * performs a safe (local) redirect, using wp_redirect() 
    522  * @return void 
     635 * wp_safe_redirect() - Performs a safe (local) redirect, using wp_redirect() 
     636 * 
     637 * @since 2.3 
     638 * 
     639 * @return void Does not return anything 
    523640 **/ 
    524641function wp_safe_redirect($location, $status = 302) { 
    …… 
    544661 
    545662if ( ! function_exists('wp_notify_postauthor') ) : 
     663/** 
     664 * wp_notify_postauthor() - Notify an author of a comment/trackback/pingback to one of their posts 
     665 * 
     666 * @since 1.0 
     667 * 
     668 * @param int $comment_id Comment ID 
     669 * @param string $comment_type Optional. The comment type either 'comment' (default), 'trackback', or 'pingback' 
     670 * @return bool False if user email does not exist. True on completion. 
     671 */ 
    546672function wp_notify_postauthor($comment_id, $comment_type='') { 
    547673    $comment = get_comment($comment_id); 
    …… 
    613739endif; 
    614740 
    615 /* wp_notify_moderator 
    616    notifies the moderator of the blog (usually the admin) 
    617    about a new comment that waits for approval 
    618    always returns true 
    619  */ 
    620741if ( !function_exists('wp_notify_moderator') ) : 
     742/** 
     743 * wp_notify_moderator() - Notifies the moderator of the blog about a new comment that is awaiting approval 
     744 * 
     745 * @since 1.0 
     746 * @uses $wpdb 
     747 * 
     748 * @param int $comment_id Comment ID 
     749 * @return bool Always returns true 
     750 */ 
    621751function wp_notify_moderator($comment_id) { 
    622752    global $wpdb; 
    …… 
    658788 
    659789if ( !function_exists('wp_new_user_notification') ) : 
     790/** 
     791 * wp_new_user_notification() - Notify the blog admin of a new user, normally via email 
     792 * 
     793 * @since 2.0 
     794 * 
     795 * @param int $user_id User ID 
     796 * @param string $plaintext_pass Optional. The user's plaintext password 
     797 */ 
    660798function wp_new_user_notification($user_id, $plaintext_pass = '') { 
    661799    $user = new WP_User($user_id); 
    …… 
    683821 
    684822if ( !function_exists('wp_verify_nonce') ) : 
     823/** 
     824 * wp_verify_nonce() - Verify that correct nonce was used with time limit 
     825 * 
     826 * The user is given an amount of time to use the token, so therefore, since 
     827 * the UID and $action remain the same, the independent variable is the time. 
     828 * 
     829 * @since 2.0.4 
     830 * 
     831 * @param string $nonce Nonce that was used in the form to verify 
     832 * @param string|int $action Should give context to what is taking place and be the same when nonce was created. 
     833 * @return bool Whether the nonce check passed or failed. 
     834 */ 
    685835function wp_verify_nonce($nonce, $action = -1) { 
    686836    $user = wp_get_current_user(); 
    …… 
    697847 
    698848if ( !function_exists('wp_create_nonce') ) : 
     849/** 
     850 * wp_create_nonce() - Creates a random, one time use token 
     851 * 
     852 * @since 2.0.4 
     853 * 
     854 * @param string|int $action Scalar value to add context to the nonce. 
     855 * @return string The one use form token 
     856 */ 
    699857function wp_create_nonce($action = -1) { 
    700858    $user = wp_get_current_user(); 
    …… 
    708866 
    709867if ( !function_exists('wp_salt') ) : 
     868/** 
     869 * wp_salt() - Get salt to add to hashes to help prevent attacks 
     870 * 
     871 * You can set the salt by defining two areas. One is in the database and 
     872 * the other is in your wp-config.php file. The database location is defined 
     873 * in the option named 'secret', but most likely will not need to be changed. 
     874 * 
     875 * The second, located in wp-config.php, is a constant named 'SECRET_KEY', but 
     876 * is not required. If the constant is not defined then the database constants 
     877 * will be used, since they are most likely given to be unique. However, given 
     878 * that the salt will be added to the password and can be seen, the constant 
     879 * is recommended to be set manually. 
     880 * 
     881 * <code> 
     882 * define('SECRET_KEY', 'mAry1HadA15|\/|b17w55w1t3asSn09w'); 
     883 * </code> 
     884 * 
     885 * Attention: Do not use above example! 
     886 * 
     887 * Salting passwords helps against tools which has stored hashed values 
     888 * of common dictionary strings. The added values makes it harder to crack 
     889 * if given salt string is not weak. 
     890 * 
     891 * Salting only helps if the string is not predictable and should be 
     892 * made up of various characters. Think of the salt as a password for 
     893 * securing your passwords, but common among all of your passwords. 
     894 * Therefore the salt should be as long as possible as as difficult as 
     895 * possible, because you will not have to remember it. 
     896 * 
     897 * @since 2.5 
     898 * 
     899 * @return string Salt value from either 'SECRET_KEY' or 'secret' option 
     900 */ 
    710901function wp_salt() { 
    711902 
    …… 
    729920 
    730921if ( !function_exists('wp_hash') ) : 
     922/** 
     923 * wp_hash() - Get hash of given string 
     924 * 
     925 * @since 2.0.4 
     926 * @uses wp_salt() Get WordPress salt 
     927 * 
     928 * @param string $data Plain text to hash 
     929 * @return string Hash of $data 
     930 */ 
    731931function wp_hash($data) { 
    732932    $salt = wp_salt(); 
    …… 
    741941 
    742942if ( !function_exists('wp_hash_password') ) : 
     943/** 
     944 * wp_hash_password() - Create a hash (encrypt) of a plain text password 
     945 * 
     946 * For integration with other applications, this function can be 
     947 * overwritten to instead use the other package password checking 
     948 * algorithm. 
     949 * 
     950 * @since 2.5 
     951 * @global object $wp_hasher PHPass object 
     952 * @uses PasswordHash::HashPassword 
     953 * 
     954 * @param string $password Plain text user password to hash 
     955 * @return string The hash string of the password 
     956 */ 
    743957function wp_hash_password($password) { 
    744958    global $wp_hasher; 
    …… 
    755969 
    756970if ( !function_exists('wp_check_password') ) : 
     971/** 
     972 * wp_check_password() - Checks the plaintext password against the encrypted Password 
     973 * 
     974 * Maintains compatibility between old version and the new cookie 
     975 * authentication protocol using PHPass library. The $hash parameter 
     976 * is the encrypted password and the function compares the plain text 
     977 * password when encypted similarly against the already encrypted 
     978 * password to see if they match. 
     979 * 
     980 * For integration with other applications, this function can be 
     981 * overwritten to instead use the other package password checking 
     982 * algorithm. 
     983 * 
     984 * @since 2.5 
     985 * @global object $wp_hasher PHPass object used for checking the password 
     986 *  against the $hash + $password 
     987 * @uses PasswordHash::CheckPassword 
     988 * 
     989 * @param string $password Plaintext user's password 
     990 * @param string $hash Hash of the user's password to check against. 
     991 * @return bool False, if the $password does not match the hashed password 
     992 */ 
    757993function wp_check_password($password, $hash) { 
    758994    global $wp_hasher; 
    …… 
    7751011if ( !function_exists('wp_generate_password') ) : 
    7761012/** 
    777  * Generates a random password drawn from the defined set of characters 
    778  * @return string the password 
     1013 * wp_generate_password() - Generates a random password drawn from the defined set of characters 
     1014 * 
     1015 * @since 2.5 
     1016 * 
     1017 * @return string The random password 
    7791018 **/ 
    7801019function wp_generate_password() { 
    …… 
    7891028 
    7901029if ( !function_exists('wp_set_password') ) : 
     1030/** 
     1031 * wp_set_password() - Updates the user's password with a new encrypted one 
     1032 * 
     1033 * For integration with other applications, this function can be 
     1034 * overwritten to instead use the other package password checking 
     1035 * algorithm. 
     1036 * 
     1037 * @since 2.5 
     1038 * @uses $wpdb WordPress database object for queries 
     1039 * @uses wp_hash_password() Used to encrypt the user's password before passing to the database 
     1040 * 
     1041 * @param string $password The plaintext new user password 
     1042 * @param int $user_id User ID 
     1043 */ 
    7911044function wp_set_password( $password, $user_id ) { 
    7921045    global $wpdb; 
    …… 
    7991052endif; 
    8001053 
    801 // Deprecated. Use wp_set_auth_cookie() 
    8021054if ( !function_exists('wp_setcookie') ) : 
     1055/** 
     1056 * wp_setcookie() - Sets a cookie for a user who just logged in 
     1057 * 
     1058 * @since 1.5 
     1059 * @deprecated Use wp_set_auth_cookie() 
     1060 * @see wp_set_auth_cookie() 
     1061 * 
     1062 * @param string  $username The user's username 
     1063 * @param string  $password Optional. The user's password 
     1064 * @param bool $already_md5 Optional. Whether the password has already been through MD5 
     1065 * @param string $home Optional. Will be used instead of COOKIEPATH if set 
     1066 * @param string $siteurl Optional. Will be used instead of SITECOOKIEPATH if set 
     1067 * @param bool $remember Optional. Remember that the user is logged in 
     1068 */ 
    8031069function wp_setcookie($username, $password = '', $already_md5 = false, $home = '', $siteurl = '', $remember = false) { 
    8041070    _deprecated_function( __FUNCTION__, '2.4', 'wp_set_auth_cookie()' ); 
    …… 
    8081074endif; 
    8091075 
    810 // Deprecated. Use wp_clear_auth_cookie() 
    8111076if ( !function_exists('wp_clearcookie') ) : 
     1077/** 
     1078 * wp_clearcookie() - Clears the authentication cookie, logging the user out 
     1079 * 
     1080 * @since 1.5 
     1081 * @deprecated Use wp_clear_auth_cookie() 
     1082 * @see wp_clear_auth_cookie() 
     1083 */ 
    8121084function wp_clearcookie() { 
    8131085    _deprecated_function( __FUNCTION__, '2.4', 'wp_clear_auth_cookie()' ); 
    …… 
    8161088endif; 
    8171089 
    818 // Deprecated.  No alternative. 
    8191090if ( !function_exists('wp_get_cookie_login') ): 
     1091/** 
     1092 * wp_get_cookie_login() - Gets the user cookie login 
     1093 * 
     1094 * This function is deprecated and should no longer be extended as it won't 
     1095 * be used anywhere in WordPress. Also, plugins shouldn't use it either. 
     1096 * 
     1097 * @since 2.0.4 
     1098 * @deprecated No alternative 
     1099 * 
     1100 * @return bool Always returns false 
     1101 */ 
    8201102function wp_get_cookie_login() { 
    8211103    _deprecated_function( __FUNCTION__, '2.4', '' );