Ticket #5512: user.phpdoc.r6473.diff

File user.phpdoc.r6473.diff, 7.1 KB (added by darkdragon, 4 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