WordPress.org

Make WordPress Core

Ticket #5512: user.phpdoc.r6473.diff

File user.phpdoc.r6473.diff, 7.1 KB (added by darkdragon, 14 years ago)

Incomplete documentation for user.php based off of r6473

  • user.php

     
    11<?php
     2/**
     3 * WordPress User API
     4 *
     5 * @package WordPress
     6 */
    27
     8/**
     9 * get_profile() - Retrieve user data based on field
     10 *
     11 * {@internal Missing Long Description}}
     12 *
     13 * @since 1.5
     14 * @uses $wpdb WordPress database object to create queries.
     15 *
     16 * @param string $field User field to retrieve
     17 * @param string $user Optional. User username.
     18 * @return string The value in the field
     19 */
    320function get_profile($field, $user = false) {
    421        global $wpdb;
    522        if ( !$user )
     
    724        return $wpdb->get_var("SELECT $field FROM $wpdb->users WHERE user_login = '$user'");
    825}
    926
     27/**
     28 * get_usernumposts() - Number of posts user has written
     29 *
     30 * @since 0.71
     31 * @uses $wpdb WordPress database object for queries
     32 *
     33 * @param int $userid User ID
     34 * @return int Amount of posts user has written
     35 */
    1036function get_usernumposts($userid) {
    1137        global $wpdb;
    1238        $userid = (int) $userid;
    1339        return $wpdb->get_var("SELECT COUNT(*) FROM $wpdb->posts WHERE post_author = '$userid' AND post_type = 'post' AND " . get_private_posts_cap_sql('post'));
    1440}
    1541
    16 // TODO: xmlrpc only.  Maybe move to xmlrpc.php.
     42/**
     43 * user_pass_ok() - {@internal Missing Short Description}}
     44 *
     45 * {@internal Missing Long Description}}
     46 *
     47 * @since
     48 * @todo xmlrpc only. Maybe move to xmlrpc.php.
     49 *
     50 * @param string $user_login {@internal Missing Description}}
     51 * @param string $user_pass {@internal Missing Description}}
     52 * @return unknown {@internal Missing Description}}
     53 */
    1754function user_pass_ok($user_login,$user_pass) {
    1855        $userdata = get_userdatabylogin($user_login);
    1956        return wp_check_password($user_pass, $userdata->user_pass);
     
    2360// User option functions
    2461//
    2562
     63/**
     64 * get_user_option() - {@internal Missing Short Description}}
     65 *
     66 * {@internal Missing Long Description}}
     67 *
     68 * @since
     69 * @uses $wpdb WordPress database object for queries
     70 *
     71 * @param string $option {@internal Missing Description}}
     72 * @param unknown_type $user Optional. {@internal Missing Description}}
     73 * @return unknown {@internal Missing Description}}
     74 */
    2675function get_user_option( $option, $user = 0 ) {
    2776        global $wpdb;
    2877
     
    3988                return get_option( $option );
    4089}
    4190
     91/**
     92 * update_user_option - {@internal Missing Short Description}}
     93 *
     94 * {@internal Missing Long Description}}
     95 *
     96 * @since
     97 * @uses $wpdb WordPress database object for queries
     98 *
     99 * @param int $user_id User ID
     100 * @param string $option_name {@internal Missing Description}}
     101 * @param mixed $newvalue {@internal Missing Description}}
     102 * @param bool $global Whether option name is blog specific or not
     103 * @return unknown
     104 */
    42105function update_user_option( $user_id, $option_name, $newvalue, $global = false ) {
    43106        global $wpdb;
    44107        if ( !$global )
     
    46109        return update_usermeta( $user_id, $option_name, $newvalue );
    47110}
    48111
    49 // Get users with capabilities for the current blog.
    50 // For setups that use the multi-blog feature.
     112/**
     113 * get_users_of_blog() - Get users with capabilities for the current blog.
     114 *
     115 * For setups that use the multi-blog feature.
     116 *
     117 * @since
     118 * @uses $wpdb WordPress database object for queries
     119 * @uses $blog_id The Blog id of the blog for those that use more than one blog
     120 *
     121 * @param int $id Blog ID
     122 * @return object|array List of Users that are part of that Blog ID
     123 */
    51124function get_users_of_blog( $id = '' ) {
    52125        global $wpdb, $blog_id;
    53126        if ( empty($id) )
     
    60133// User meta functions
    61134//
    62135
     136/**
     137 * delete_usermeta() - {@internal Missing Short Description}}
     138 *
     139 * {@internal Missing Long Description}}
     140 *
     141 * @since
     142 * @uses $wpdb WordPress database object for queries
     143 *
     144 * @param int $user_id User ID
     145 * @param string $meta_key {@internal Missing Description}}
     146 * @param mixed $meta_value {@internal Missing Description}}
     147 * @return bool True deletion completed and false if user_id is not a number.
     148 */
    63149function delete_usermeta( $user_id, $meta_key, $meta_value = '' ) {
    64150        global $wpdb;
    65151        if ( !is_numeric( $user_id ) )
     
    80166        return true;
    81167}
    82168
     169/**
     170 * get_usermeta() - {@internal Missing Short Description}}
     171 *
     172 * If $user_id is not a number, then the function will fail over
     173 * with a 'false' boolean return value.
     174 * {@internal Missing Long Description}}
     175 *
     176 * @since
     177 * @uses $wpdb WordPress database object for queries
     178 *
     179 * @param int $user_id User ID
     180 * @param string $meta_key {@internal Missing Description}}
     181 * @return false|string|array
     182 */
    83183function get_usermeta( $user_id, $meta_key = '') {
    84184        global $wpdb;
    85185        $user_id = (int) $user_id;
     
    110210                return $values;
    111211}
    112212
     213/**
     214 * update_usermeta() - {@internal Missing Short Description}}
     215 *
     216 * {@internal Missing Long Description}}
     217 *
     218 * @since
     219 * @uses $wpdb WordPress database object for queries
     220 *
     221 * @param int $user_id User ID
     222 * @param string $meta_key
     223 * @param mixed $meta_value
     224 * @return unknown
     225 */
    113226function update_usermeta( $user_id, $meta_key, $meta_value ) {
    114227        global $wpdb;
    115228        if ( !is_numeric( $user_id ) )
    116229                return false;
    117230        $meta_key = preg_replace('|[^a-z0-9_]|i', '', $meta_key);
    118231
    119         // FIXME: usermeta data is assumed to be already escaped
     232        /** @todo Might need fix because usermeta data is assumed to be already escaped */
    120233        if ( is_string($meta_value) )
    121234                $meta_value = stripslashes($meta_value);
    122235        $meta_value = maybe_serialize($meta_value);
     
    146259// Private helper functions
    147260//
    148261
    149 // Setup global user vars.  Used by set_current_user() for back compat.
     262/**
     263 * setup_userdata() - Setup global user vars.
     264 *
     265 * Used by set_current_user() for back compat. Might be deprecated
     266 * in the future.
     267 *
     268 * @since
     269 * @global unknown $userdata
     270 * @global string $user_login The user username for logging in
     271 * @global int $user_level The level of the user
     272 * @global int $user_ID The ID of the user
     273 * @global string $user_email The email address of the user
     274 * @global string $user_url The url in the user's profile
     275 * @global string $user_pass_md5 MD5 of the user's password
     276 * @global string $user_identity The display name of the user
     277 *
     278 * @param int $user_id Optional. User ID to setup data for
     279 */
    150280function setup_userdata($user_id = '') {
    151281        global $user_login, $userdata, $user_level, $user_ID, $user_email, $user_url, $user_pass_md5, $user_identity;
    152282
     
    168298        $user_identity  = $user->display_name;
    169299}
    170300
     301/**
     302 * wp_dropdown_users() - {@internal Missing Short Description}}
     303 *
     304 * {@internal Missing Long Description}}
     305 *
     306 * @since
     307 * @uses $wpdb WordPress database object for queries
     308 *
     309 * @param unknown_type $args
     310 * @return unknown
     311 */
    171312function wp_dropdown_users( $args = '' ) {
    172313        global $wpdb;
    173314        $defaults = array(
     
    233374        return $output;
    234375}
    235376
     377/**
     378 * _fill_user() - {@internal Missing Short Description}}
     379 *
     380 * {@internal Missing Long Description}}
     381 *
     382 * @access private
     383 * @since
     384 * @uses $wpdb WordPress database object for queries
     385 *
     386 * @param object $user The user data object
     387 */
    236388function _fill_user( &$user ) {
    237389        global $wpdb;
    238390