WordPress.org
Get WordPress

Make WordPress Core


Ignore:
Timestamp:
01/11/2008 08:51:39 PM (17 years ago)
Author:
ryan
Message:

phpdoc for pluggable from darkdragon. fixes #5509

File:
1 edited

Legend:

Unmodified
Added
Removed

  • 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', '' );
Note: See TracChangeset for help on using the changeset viewer.