Changeset 8215

Show
Ignore:
Timestamp:
06/30/08 03:23:44 (4 months ago)
Author:
ryan
Message:

phpdoc updates from jacobsantos. see #5639

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • trunk/wp-includes/functions.php

    r8212 r8215  
    100100} 
    101101 
    102  
     102/** 
     103 * Retrieve the date in localized format, based on timestamp. 
     104 * 
     105 * If the locale specifies the locale month and weekday, then the locale will 
     106 * take over the format for the date. If it isn't, then the date format string 
     107 * will be used instead. 
     108 * 
     109 * @since 0.71 
     110 * 
     111 * @param string $dateformatstring Format to display the date 
     112 * @param int $unixtimestamp Unix timestamp 
     113 * @return string The date, translated if locale specifies it. 
     114 */ 
    103115function date_i18n( $dateformatstring, $unixtimestamp ) { 
    104116    global $wp_locale; 
    …… 
    281293} 
    282294 
    283 /* Options functions */ 
    284  
    285295/** 
    286296 * Retrieve option value based on setting name. 
    287297 * 
    288  * {@internal Missing Long Description}} 
     298 * If the option does not exist or does not have a value, then the return value 
     299 * will be false. This is useful to check whether you need to install an option 
     300 * and is commonly used during installation of plugin options and to test 
     301 * whether upgrading is required. 
     302 * 
     303 * You can "short-circuit" the retrieval of the option from the database for 
     304 * your plugin or core options that aren't protected. You can do so by hooking 
     305 * into the 'pre_option_$option' with the $option being replaced by the option 
     306 * name. You should not try to override special options, but you will not be 
     307 * prevented from doing so. 
     308 * 
     309 * There is a second filter called 'option_$option' with the $option being 
     310 * replaced with the option name. This gives the value as the only parameter. 
    289311 * 
    290312 * @since 1.5.0 
    291313 * @package WordPress 
    292314 * @subpackage Option 
     315 * @uses apply_filters() Calls 'pre_option_$optionname' false to allow 
     316 *      overwriting the option value in a plugin. 
     317 * @uses apply_filters() Calls 'option_$optionname' with the option name value. 
    293318 * 
    294319 * @param string $setting Name of option to retrieve. Should already be SQL-escaped 
    …… 
    375400} 
    376401 
     402/** 
     403 * Retrieve all autoload options or all options, if no autoloaded ones exist. 
     404 * 
     405 * This is different from wp_load_alloptions(), in this that function does not 
     406 * cache all options and will retrieve all options from the database every time 
     407 * it is called. 
     408 * 
     409 * @since 1.0.0 
     410 * @package WordPress 
     411 * @subpackage Option 
     412 * @uses apply_filters() Calls 'pre_option_$optionname' hook with option value as parameter. 
     413 * @uses apply_filters() Calls 'all_options' on options list. 
     414 * 
     415 * @return array List of all options. 
     416 */ 
    377417function get_alloptions() { 
    378418    global $wpdb, $wp_queries; 
    …… 
    393433} 
    394434 
    395  
     435/** 
     436 * Loads and caches all autoloaded options, if available or all options. 
     437 * 
     438 * This is different from get_alloptions(), in that this function will cache the 
     439 * options and will return the cached options when called again. 
     440 * 
     441 * @since 2.2.0 
     442 * @package WordPress 
     443 * @subpackage Option 
     444 * 
     445 * @return array List all options. 
     446 */ 
    396447function wp_load_alloptions() { 
    397448    global $wpdb; 
    …… 
    412463} 
    413464 
    414  
    415 // expects $option_name to NOT be SQL-escaped 
     465/** 
     466 * Update the value of an option that was already added. 
     467 * 
     468 * If the option does not exist, then the option will be added with the option 
     469 * value, but you will not be able to set whether it is autoloaded. If you want 
     470 * to set whether an option autoloaded, then you need to use the add_option(). 
     471 * 
     472 * When the option is updated, then the filter named 
     473 * 'update_option_$option_name', with the $option_name as the $option_name 
     474 * parameter value, will be called. The hook should accept two parameters, the 
     475 * first is the old parameter and the second is the new parameter. 
     476 * 
     477 * @since 1.0.0 
     478 * @package WordPress 
     479 * @subpackage Option 
     480 * 
     481 * @param string $option_name Option name. Expected to not be SQL-escaped 
     482 * @param mixed $newvalue Option value. 
     483 * @return bool False if value was not updated and true if value was updated. 
     484 */ 
    416485function update_option( $option_name, $newvalue ) { 
    417486    global $wpdb; 
    …… 
    457526} 
    458527 
    459  
    460 // thx Alex Stapleton, http://alex.vort-x.net/blog/ 
    461 // expects $name to NOT be SQL-escaped 
     528/** 
     529 * Add a new option. 
     530 * 
     531 * You can create options without values and then add values later. Does not 
     532 * check whether the option has already been added, but does check that you 
     533 * aren't adding a protected WordPress option. Care should be taken to not name 
     534 * options, the same as the ones which are protected and to not add options 
     535 * that were already added. 
     536 * 
     537 * The filter named 'add_option_$optionname', with the $optionname being 
     538 * replaced with the option's name, will be called. The hook should accept two 
     539 * parameters, the first is the option name, and the second is the value. 
     540 * 
     541 * @package WordPress 
     542 * @subpackage Option 
     543 * @since 1.0.0 
     544 * @link http://alex.vort-x.net/blog/ Thanks Alex Stapleton 
     545 * 
     546 * @param string $name Option name to add. Expects to NOT be SQL escaped. 
     547 * @param mixed $value Optional. Option value, can be anything. 
     548 * @param mixed $deprecated Optional. Description. Not used anymore. 
     549 * @param bool $autoload Optional. Default is enabled. Whether to load the option when WordPress starts up. 
     550 * @return null returns when finished. 
     551 */ 
    462552function add_option( $name, $value = '', $deprecated = '', $autoload = 'yes' ) { 
    463553    global $wpdb; 
    …… 
    493583    $wpdb->query( $wpdb->prepare( "INSERT INTO $wpdb->options (option_name, option_value, autoload) VALUES (%s, %s, %s)", $name, $value, $autoload ) ); 
    494584 
    495     do_action( "add_option_{$name}", $name, $value );  
     585    do_action( "add_option_{$name}", $name, $value ); 
    496586    return; 
    497587} 
    498588 
    499  
     589/** 
     590 * Removes option by name and prevents removal of protected WordPress options. 
     591 * 
     592 * @package WordPress 
     593 * @subpackage Option 
     594 * @since unknown 
     595 * 
     596 * @param string $name Option name to remove. 
     597 * @return bool True, if succeed. False, if failure. 
     598 */ 
    500599function delete_option( $name ) { 
    501600    global $wpdb; 
    …… 
    522621} 
    523622 
    524  
     623/** 
     624 * Serialize data, if needed. 
     625 * 
     626 * @param mixed $data Data that might be serialized. 
     627 * @return mixed A scalar data 
     628 */ 
    525629function maybe_serialize( $data ) { 
    526630    if ( is_string( $data ) ) 
    …… 
    586690} 
    587691 
    588  
     692/** 
     693 * Open the file handle for debugging. 
     694 * 
     695 * This function is used for XMLRPC feature, but it is general purpose enough 
     696 * to be used in anywhere. 
     697 * 
     698 * @see fopen() for mode options. 
     699 * @package WordPress 
     700 * @subpackage Debug 
     701 * @since unknown 
     702 * @uses $debug Used for whether debugging is enabled. 
     703 * 
     704 * @param string $filename File path to debug file. 
     705 * @param string $mode Same as fopen() mode parameter. 
     706 * @return bool|resource File handle. False on failure. 
     707 */ 
    589708function debug_fopen( $filename, $mode ) { 
    590709    global $debug; 
    …… 
    597716} 
    598717 
    599  
     718/** 
     719 * Write contents to the file used for debugging. 
     720 * 
     721 * Technically, this can be used to write to any file handle when the global 
     722 * $debug is set to 1 or true. 
     723 * 
     724 * @package WordPress 
     725 * @subpackage Debug 
     726 * @since unknown 
     727 * @uses $debug Used for whether debugging is enabled. 
     728 * 
     729 * @param resource $fp File handle for debugging file. 
     730 * @param string $string Content to write to debug file. 
     731 */ 
    600732function debug_fwrite( $fp, $string ) { 
    601733    global $debug; 
    …… 
    604736} 
    605737 
    606  
     738/** 
     739 * Close the debugging file handle. 
     740 * 
     741 * Technically, this can be used to close any file handle when the global $debug 
     742 * is set to 1 or true. 
     743 * 
     744 * @package WordPress 
     745 * @subpackage Debug 
     746 * @since unknown 
     747 * @uses $debug Used for whether debugging is enabled. 
     748 * 
     749 * @param resource $fp Debug File handle. 
     750 */ 
    607751function debug_fclose( $fp ) { 
    608752    global $debug; 
    …… 
    773917} 
    774918 
    775  
     919/** 
     920 * Build URL query based on an associative and, or indexed array. 
     921 * 
     922 * This is a convenient function for easily building url queries. It sets the 
     923 * separator to '&' and uses _http_build_query() function. 
     924 * 
     925 * @see _http_build_query() Used to build the query 
     926 * @link http://us2.php.net/manual/en/function.http-build-query.php more on what 
     927 *      http_build_query() does. 
     928 * 
     929 * @since unknown 
     930 * 
     931 * @param array $data URL-encode key/value pairs. 
     932 * @return string URL encoded string 
     933 */ 
    776934function build_query( $data ) { 
    777935    return _http_build_query( $data, NULL, '&', '', false ); 
    …… 
    779937 
    780938/** 
    781  * Retrieve a modified query string. 
    782  * 
    783  * {@internal Missing Long Description}} 
    784  * 
    785  * Adding a single key & value or an associative array. 
    786  * Setting a key value to emptystring removes the key. 
    787  * Omitting oldquery_or_uri uses the $_SERVER value. 
     939 * Retrieve a modified URL query string. 
     940 * 
     941 * You can rebuild the URL and append a new query variable to the URL query by 
     942 * using this function. You can also retrieve the full URL with query data. 
     943 * 
     944 * Adding a single key & value or an associative array. Setting a key value to 
     945 * emptystring removes the key. Omitting oldquery_or_uri uses the $_SERVER 
     946 * value. 
    788947 * 
    789948 * @since 1.5.0 
    …… 
    8981057} 
    8991058 
     1059/** 
     1060 * HTTP request for URI to retrieve content. 
     1061 * 
     1062 * Tries to retrieve the HTTP content with fopen first and then using cURL, if 
     1063 * fopen can't be used. 
     1064 * 
     1065 * @since unknown 
     1066 * 
     1067 * @param string $uri URI/URL of web page to retrieve. 
     1068 * @return string HTTP content. 
     1069 */ 
    9001070function wp_remote_fopen( $uri ) { 
    9011071    $timeout = 10; 
    …… 
    10091179} 
    10101180 
    1011  
     1181/** 
     1182 * Set HTTP status header. 
     1183 * 
     1184 * @since unknown 
     1185 * @uses apply_filters() Calls 'status_header' on status header string, HTTP 
     1186 *      HTTP code, HTTP code description, and protocol string as separate 
     1187 *      parameters. 
     1188 * 
     1189 * @param int $header HTTP status code 
     1190 * @return null Does not return anything. 
     1191 */ 
    10121192function status_header( $header ) { 
    10131193    $text = get_status_header_desc( $header ); 
    …… 
    17951975} 
    17961976 
    1797  
    17981977/** 
    17991978 * Load the correct database class file. 
    …… 
    18131992        require_once( ABSPATH . WPINC . '/wp-db.php' ); 
    18141993} 
    1815  
    18161994 
    18171995/** 
    …… 
    18622040} 
    18632041 
    1864  
    18652042/** 
    18662043 * Converts value to positive integer. 
    …… 
    18742051    return abs( intval( $maybeint ) ); 
    18752052} 
    1876  
    18772053 
    18782054/** 
    …… 
    19082084    return false; 
    19092085} 
    1910  
    19112086 
    19122087/** 
    …… 
    19262101} 
    19272102 
    1928  
    19292103/** 
    19302104 * Marks a function as deprecated and informs when it has been used. 
    …… 
    19642138} 
    19652139 
    1966  
    19672140/** 
    19682141 * Marks a file as deprecated and informs when it has been used. 
    …… 
    20022175} 
    20032176 
    2004  
    20052177/** 
    20062178 * Is the server running earlier than 1.5.0 version of lighttpd 
    …… 
    20152187    return  'lighttpd' == $server_parts[0] && -1 == version_compare( $server_parts[1], '1.5.0' ); 
    20162188} 
    2017  
    20182189 
    20192190/** 
    …… 
    20462217} 
    20472218 
    2048  
    20492219/** 
    20502220 * File validates against allowed set of defined rules. 
    …… 
    20772247} 
    20782248 
    2079  
    20802249/** 
    20812250 * Determine if SSL is used. 
    …… 
    20882257    return ( 'on' == strtolower($_SERVER['HTTPS']) ) ? true : false;  
    20892258} 
    2090  
    20912259 
    20922260/** 
    …… 
    21102278} 
    21112279 
    2112  
    21132280/** 
    21142281 * Whether to force SSL used for the Administration Panels. 
    …… 
    21312298} 
    21322299 
     2300/** 
     2301 * Guess the URL for the site. 
     2302 * 
     2303 * Will remove wp-admin links to retrieve only return URLs not in the wp-admin 
     2304 * directory. 
     2305 * 
     2306 * @since 2.6 
     2307 * 
     2308 * @return string 
     2309 */ 
    21332310function wp_guess_url() { 
    21342311    if ( defined('WP_SITEURL') && '' != WP_SITEURL ) {