WordPress-C
/
WordPress
mirror of https://github.com/WordPress/WordPress.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

General inline documentation improvements in wp-includes/functions.php. 

Final run. Fixes #26185.

Built from https://develop.svn.wordpress.org/trunk@29011


git-svn-id: http://core.svn.wordpress.org/trunk@28799 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
Drew Jaynes 2014-07-07 06:19:14 +00:00
parent bf9908b37f
commit 9f8ddaa627
1 changed files with 162 additions and 120 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

272
wp-includes/functions.php
View File

@ -674,8 +674,9 @@ function build_query( $data ) {
* From php.net (modified by Mark Jaquith to behave like the native PHP5 function). * From php.net (modified by Mark Jaquith to behave like the native PHP5 function).
* *
* @since 3.2.0 * @since 3.2.0
* @access private
* *
* @link http://us1.php.net/manual/en/function.http-build-query.php * @see http://us1.php.net/manual/en/function.http-build-query.php
* *
* @param array|object $data An array or object of data. Converted to array. * @param array|object $data An array or object of data. Converted to array.
* @param string $prefix Optional. Numeric index. If set, start parameter numbering with it. * @param string $prefix Optional. Numeric index. If set, start parameter numbering with it.
@ -3145,19 +3146,19 @@ function dead_db() {
} }
/** /**
* Converts value to nonnegative integer. * Convert a value to non-negative integer.
* *
* @since 2.5.0 * @since 2.5.0
* *
* @param mixed $maybeint Data you wish to have converted to a nonnegative integer * @param mixed $maybeint Data you wish to have converted to a non-negative integer.
* @return int An nonnegative integer * @return int A non-negative integer.
*/ */
function absint( $maybeint ) { function absint( $maybeint ) {
return abs( intval( $maybeint ) ); return abs( intval( $maybeint ) );
} }
/** /**
* Marks a function as deprecated and informs when it has been used. * Mark a function as deprecated and informs when it has been used.
* *
* There is a hook deprecated_function_run that will be called that can be used * There is a hook deprecated_function_run that will be called that can be used
* to get the backtrace up to what file and function called the deprecated * to get the backtrace up to what file and function called the deprecated
@ -3170,9 +3171,9 @@ function absint( $maybeint ) {
* @since 2.5.0 * @since 2.5.0
* @access private * @access private
* *
* @param string $function The function that was called * @param string $function The function that was called.
* @param string $version The version of WordPress that deprecated the function * @param string $version The version of WordPress that deprecated the function.
* @param string $replacement Optional. The function that should have been called * @param string $replacement Optional. The function that should have been called. Default null.
*/ */
function _deprecated_function( $function, $version, $replacement = null ) { function _deprecated_function( $function, $version, $replacement = null ) {
@ -3210,7 +3211,7 @@ function _deprecated_function( $function, $version, $replacement = null ) {
} }
/** /**
* Marks a file as deprecated and informs when it has been used. * Marks a file as deprecated and inform when it has been used.
* *
* There is a hook deprecated_file_included that will be called that can be used * There is a hook deprecated_file_included that will be called that can be used
* to get the backtrace up to what file and function included the deprecated * to get the backtrace up to what file and function included the deprecated
@ -3223,10 +3224,11 @@ function _deprecated_function( $function, $version, $replacement = null ) {
* @since 2.5.0 * @since 2.5.0
* @access private * @access private
* *
* @param string $file The file that was included * @param string $file The file that was included.
* @param string $version The version of WordPress that deprecated the file * @param string $version The version of WordPress that deprecated the file.
* @param string $replacement Optional. The file that should have been included based on ABSPATH * @param string $replacement Optional. The file that should have been included based on ABSPATH.
* @param string $message Optional. A message regarding the change * Default null.
* @param string $message Optional. A message regarding the change. Default empty.
*/ */
function _deprecated_file( $file, $version, $replacement = null, $message = '' ) { function _deprecated_file( $file, $version, $replacement = null, $message = '' ) {
@ -3265,7 +3267,7 @@ function _deprecated_file( $file, $version, $replacement = null, $message = '' )
} }
} }
/** /**
* Marks a function argument as deprecated and informs when it has been used. * Mark a function argument as deprecated and inform when it has been used.
* *
* This function is to be used whenever a deprecated function argument is used. * This function is to be used whenever a deprecated function argument is used.
* Before this function is called, the argument must be checked for whether it was * Before this function is called, the argument must be checked for whether it was
@ -3285,9 +3287,9 @@ function _deprecated_file( $file, $version, $replacement = null, $message = '' )
* @since 3.0.0 * @since 3.0.0
* @access private * @access private
* *
* @param string $function The function that was called * @param string $function The function that was called.
* @param string $version The version of WordPress that deprecated the argument used * @param string $version The version of WordPress that deprecated the argument used.
* @param string $message Optional. A message regarding the change. * @param string $message Optional. A message regarding the change. Default null.
*/ */
function _deprecated_argument( $function, $version, $message = null ) { function _deprecated_argument( $function, $version, $message = null ) {
@ -3325,7 +3327,7 @@ function _deprecated_argument( $function, $version, $message = null ) {
} }
/** /**
* Marks something as being incorrectly called. * Mark something as being incorrectly called.
* *
* There is a hook doing_it_wrong_run that will be called that can be used * There is a hook doing_it_wrong_run that will be called that can be used
* to get the backtrace up to what file and function called the deprecated * to get the backtrace up to what file and function called the deprecated
@ -3378,7 +3380,7 @@ function _doing_it_wrong( $function, $message, $version ) {
* *
* @since 2.5.0 * @since 2.5.0
* *
* @return bool Whether the server is running lighttpd < 1.5.0 * @return bool Whether the server is running lighttpd < 1.5.0.
*/ */
function is_lighttpd_before_150() { function is_lighttpd_before_150() {
$server_parts = explode( '/', isset( $_SERVER['SERVER_SOFTWARE'] )? $_SERVER['SERVER_SOFTWARE'] : '' ); $server_parts = explode( '/', isset( $_SERVER['SERVER_SOFTWARE'] )? $_SERVER['SERVER_SOFTWARE'] : '' );
@ -3391,9 +3393,9 @@ function is_lighttpd_before_150() {
* *
* @since 2.5.0 * @since 2.5.0
* *
* @param string $mod e.g. mod_rewrite * @param string $mod The module, e.g. mod_rewrite.
* @param bool $default The default return value if the module is not found * @param bool $default Optional. The default return value if the module is not found. Default false.
* @return bool * @return bool Whether the specified module is loaded.
*/ */
function apache_mod_loaded($mod, $default = false) { function apache_mod_loaded($mod, $default = false) {
global $is_apache; global $is_apache;
@ -3420,7 +3422,7 @@ function apache_mod_loaded($mod, $default = false) {
* *
* @since 2.8.0 * @since 2.8.0
* *
* @return bool * @return bool Whether IIS7 supports permalinks.
*/ */
function iis7_supports_permalinks() { function iis7_supports_permalinks() {
global $is_iis7; global $is_iis7;
@ -3504,7 +3506,7 @@ function is_ssl() {
* @since 4.0.0 * @since 4.0.0
* *
* @param string $url The URL * @param string $url The URL
* @return boolean True if the given URL uses https, false if not (or if the URL is not valid). * @return bool True if the given URL uses https, false if not (or if the URL is not valid).
*/ */
function is_https_url( $url ) { function is_https_url( $url ) {
return ( 'https' === parse_url( $url, PHP_URL_SCHEME ) ); return ( 'https' === parse_url( $url, PHP_URL_SCHEME ) );
@ -3515,7 +3517,9 @@ function is_https_url( $url ) {
* *
* @since 2.6.0 * @since 2.6.0
* *
* @param string|bool $force Optional. * @see force_ssl_admin()
*
* @param string|bool $force Optional Whether to force SSL login. Default null.
* @return bool True if forced, false if not forced. * @return bool True if forced, false if not forced.
*/ */
function force_ssl_login( $force = null ) { function force_ssl_login( $force = null ) {
@ -3527,7 +3531,7 @@ function force_ssl_login( $force = null ) {
* *
* @since 2.6.0 * @since 2.6.0
* *
* @param string|bool $force * @param string|bool $force Optional. Whether to force SSL in admin screens. Default null.
* @return bool True if forced, false if not forced. * @return bool True if forced, false if not forced.
*/ */
function force_ssl_admin( $force = null ) { function force_ssl_admin( $force = null ) {
@ -3550,7 +3554,7 @@ function force_ssl_admin( $force = null ) {
* *
* @since 2.6.0 * @since 2.6.0
* *
* @return string * @return string The guessed URL.
*/ */
function wp_guess_url() { function wp_guess_url() {
if ( defined('WP_SITEURL') && '' != WP_SITEURL ) { if ( defined('WP_SITEURL') && '' != WP_SITEURL ) {
@ -3618,14 +3622,14 @@ function wp_suspend_cache_addition( $suspend = null ) {
/** /**
* Suspend cache invalidation. * Suspend cache invalidation.
* *
* Turns cache invalidation on and off. Useful during imports where you don't wont to do invalidations * Turns cache invalidation on and off. Useful during imports where you don't wont to do
* every time a post is inserted. Callers must be sure that what they are doing won't lead to an inconsistent * invalidations every time a post is inserted. Callers must be sure that what they are
* cache when invalidation is suspended. * doing won't lead to an inconsistent cache when invalidation is suspended.
* *
* @since 2.7.0 * @since 2.7.0
* *
* @param bool $suspend Whether to suspend or enable cache invalidation * @param bool $suspend Optional. Whether to suspend or enable cache invalidation. Default true.
* @return bool The current suspend setting * @return bool The current suspend setting.
*/ */
function wp_suspend_cache_invalidation( $suspend = true ) { function wp_suspend_cache_invalidation( $suspend = true ) {
global $_wp_suspend_cache_invalidation; global $_wp_suspend_cache_invalidation;
@ -3636,12 +3640,14 @@ function wp_suspend_cache_invalidation($suspend = true) {
} }
/** /**
* Whether a site is the main site of the current network. * Determine whether a site is the main site of the current network.
* *
* @since 3.0.0 * @since 3.0.0
* *
* @param int $site_id Optional. Site ID to test. Defaults to current site. * @param int $site_id Optional. Site ID to test. Defaults to current site.
* @return bool True if $site_id is the main site of the network, or if not running multisite. * Defaults to current site.
* @return bool True if $site_id is the main site of the network, or if not
* running Multisite.
*/ */
function is_main_site( $site_id = null ) { function is_main_site( $site_id = null ) {
// This is the current network's information; 'site' is old terminology. // This is the current network's information; 'site' is old terminology.
@ -3657,12 +3663,12 @@ function is_main_site( $site_id = null ) {
} }
/** /**
* Whether a network is the main network of the multisite install. * Determine whether a network is the main network of the Multisite install.
* *
* @since 3.7.0 * @since 3.7.0
* *
* @param int $network_id Optional. Network ID to test. Defaults to current network. * @param int $network_id Optional. Network ID to test. Defaults to current network.
* @return bool True if $network_id is the main network, or if not running multisite. * @return bool True if $network_id is the main network, or if not running Multisite.
*/ */
function is_main_network( $network_id = null ) { function is_main_network( $network_id = null ) {
global $wpdb; global $wpdb;
@ -3694,12 +3700,11 @@ function is_main_network( $network_id = null ) {
} }
/** /**
* Whether global terms are enabled. * Determine whether global terms are enabled.
*
* *
* @since 3.0.0 * @since 3.0.0
* *
* @return bool True if multisite and global terms enabled * @return bool True if multisite and global terms enabled.
*/ */
function global_terms_enabled() { function global_terms_enabled() {
if ( ! is_multisite() ) if ( ! is_multisite() )
@ -3734,7 +3739,7 @@ function global_terms_enabled() {
* *
* @since 2.8.0 * @since 2.8.0
* *
* @return float|bool * @return float|bool Timezone GMT offset, false otherwise.
*/ */
function wp_timezone_override_offset() { function wp_timezone_override_offset() {
if ( !$timezone_string = get_option( 'timezone_string' ) ) { if ( !$timezone_string = get_option( 'timezone_string' ) ) {
@ -3753,6 +3758,7 @@ function wp_timezone_override_offset() {
* Sort-helper for timezones. * Sort-helper for timezones.
* *
* @since 2.9.0 * @since 2.9.0
* @access private
* *
* @param array $a * @param array $a
* @param array $b * @param array $b
@ -3797,11 +3803,11 @@ function _wp_timezone_choice_usort_callback( $a, $b ) {
} }
/** /**
* Gives a nicely formatted list of timezone strings. * Gives a nicely-formatted list of timezone strings.
* *
* @since 2.9.0 * @since 2.9.0
* *
* @param string $selected_zone Selected Zone * @param string $selected_zone Selected timezone.
* @return string * @return string
*/ */
function wp_timezone_choice( $selected_zone ) { function wp_timezone_choice( $selected_zone ) {
@ -3927,11 +3933,13 @@ function wp_timezone_choice( $selected_zone ) {
/** /**
* Strip close comment and close php tags from file headers used by WP. * Strip close comment and close php tags from file headers used by WP.
* See http://core.trac.wordpress.org/ticket/8497
* *
* @since 2.8.0 * @since 2.8.0
* @access private
* *
* @param string $str * @see http://core.trac.wordpress.org/ticket/8497
*
* @param string $str Header comment to clean up.
* @return string * @return string
*/ */
function _cleanup_header_comment( $str ) { function _cleanup_header_comment( $str ) {
@ -3939,7 +3947,8 @@ function _cleanup_header_comment($str) {
} }
/** /**
* Permanently deletes posts, pages, attachments, and comments which have been in the trash for EMPTY_TRASH_DAYS. * Permanently delete posts, pages, attachments, and comments which have been
* in the trash for EMPTY_TRASH_DAYS.
* *
* @since 2.9.0 * @since 2.9.0
*/ */
@ -3996,9 +4005,10 @@ function wp_scheduled_delete() {
* @see http://codex.wordpress.org/File_Header * @see http://codex.wordpress.org/File_Header
* *
* @since 2.9.0 * @since 2.9.0
* @param string $file Path to the file * @param string $file Path to the file.
* @param array $default_headers List of headers, in the format array('HeaderKey' => 'Header Name') * @param array $default_headers List of headers, in the format array('HeaderKey' => 'Header Name').
* @param string $context If specified adds filter hook "extra_{$context}_headers" * @param string $context Optional. If specified adds filter hook "extra_{$context}_headers".
* Default empty.
*/ */
function get_file_data( $file, $default_headers, $context = '' ) { function get_file_data( $file, $default_headers, $context = '' ) {
// We don't need to write to the file, so just open for reading. // We don't need to write to the file, so just open for reading.
@ -4046,8 +4056,10 @@ function get_file_data( $file, $default_headers, $context = '' ) {
* Useful for returning true to filters easily. * Useful for returning true to filters easily.
* *
* @since 3.0.0 * @since 3.0.0
*
* @see __return_false() * @see __return_false()
* @return bool true *
* @return bool True.
*/ */
function __return_true() { function __return_true() {
return true; return true;
@ -4059,8 +4071,10 @@ function __return_true() {
* Useful for returning false to filters easily. * Useful for returning false to filters easily.
* *
* @since 3.0.0 * @since 3.0.0
*
* @see __return_true() * @see __return_true()
* @return bool false *
* @return bool False.
*/ */
function __return_false() { function __return_false() {
return false; return false;
@ -4072,7 +4086,8 @@ function __return_false() {
* Useful for returning 0 to filters easily. * Useful for returning 0 to filters easily.
* *
* @since 3.0.0 * @since 3.0.0
* @return int 0 *
* @return int 0.
*/ */
function __return_zero() { function __return_zero() {
return 0; return 0;
@ -4084,7 +4099,8 @@ function __return_zero() {
* Useful for returning an empty array to filters easily. * Useful for returning an empty array to filters easily.
* *
* @since 3.0.0 * @since 3.0.0
* @return array Empty array *
* @return array Empty array.
*/ */
function __return_empty_array() { function __return_empty_array() {
return array(); return array();
@ -4096,7 +4112,8 @@ function __return_empty_array() {
* Useful for returning null to filters easily. * Useful for returning null to filters easily.
* *
* @since 3.4.0 * @since 3.4.0
* @return null *
* @return null Null value.
*/ */
function __return_null() { function __return_null() {
return null; return null;
@ -4108,8 +4125,10 @@ function __return_null() {
* Useful for returning an empty string to filters easily. * Useful for returning an empty string to filters easily.
* *
* @since 3.7.0 * @since 3.7.0
*
* @see __return_null() * @see __return_null()
* @return string Empty string *
* @return string Empty string.
*/ */
function __return_empty_string() { function __return_empty_string() {
return ''; return '';
@ -4118,23 +4137,23 @@ function __return_empty_string() {
/** /**
* Send a HTTP header to disable content type sniffing in browsers which support it. * Send a HTTP header to disable content type sniffing in browsers which support it.
* *
* @link http://blogs.msdn.com/ie/archive/2008/07/02/ie8-security-part-v-comprehensive-protection.aspx
* @link http://src.chromium.org/viewvc/chrome?view=rev&revision=6985
*
* @since 3.0.0 * @since 3.0.0
* @return none *
* @see http://blogs.msdn.com/ie/archive/2008/07/02/ie8-security-part-v-comprehensive-protection.aspx
* @see http://src.chromium.org/viewvc/chrome?view=rev&revision=6985
*/ */
function send_nosniff_header() { function send_nosniff_header() {
@header( 'X-Content-Type-Options: nosniff' ); @header( 'X-Content-Type-Options: nosniff' );
} }
/** /**
* Returns a MySQL expression for selecting the week number based on the start_of_week option. * Return a MySQL expression for selecting the week number based on the start_of_week option.
* *
* @internal * @internal
* @since 3.0.0 * @since 3.0.0
* @param string $column *
* @return string * @param string $column Database column.
* @return string SQL clause.
*/ */
function _wp_mysql_week( $column ) { function _wp_mysql_week( $column ) {
switch ( $start_of_week = (int) get_option( 'start_of_week' ) ) { switch ( $start_of_week = (int) get_option( 'start_of_week' ) ) {
@ -4153,16 +4172,17 @@ function _wp_mysql_week( $column ) {
} }
/** /**
* Finds hierarchy loops using a callback function that maps object IDs to parent IDs. * Find hierarchy loops using a callback function that maps object IDs to parent IDs.
* *
* @since 3.1.0 * @since 3.1.0
* @access private * @access private
* *
* @param callback $callback function that accepts ( ID, $callback_args ) and outputs parent_ID * @param callback $callback Function that accepts ( ID, $callback_args ) and outputs parent_ID.
* @param int $start The ID to start the loop check at * @param int $start The ID to start the loop check at.
* @param int $start_parent the parent_ID of $start to use instead of calling $callback( $start ). Use null to always use $callback * @param int $start_parent The parent_ID of $start to use instead of calling $callback( $start ).
* @param array $callback_args optional additional arguments to send to $callback * Use null to always use $callback
* @return array IDs of all members of loop * @param array $callback_args Optional. Additional arguments to send to $callback.
* @return array IDs of all members of loop.
*/ */
function wp_find_hierarchy_loop( $callback, $start, $start_parent, $callback_args = array() ) { function wp_find_hierarchy_loop( $callback, $start, $start_parent, $callback_args = array() ) {
$override = is_null( $start_parent ) ? array() : array( $start => $start_parent ); $override = is_null( $start_parent ) ? array() : array( $start => $start_parent );
@ -4174,7 +4194,7 @@ function wp_find_hierarchy_loop( $callback, $start, $start_parent, $callback_arg
} }
/** /**
* Uses the "The Tortoise and the Hare" algorithm to detect loops. * Use the "The Tortoise and the Hare" algorithm to detect loops.
* *
* For every step of the algorithm, the hare takes two steps and the tortoise one. * For every step of the algorithm, the hare takes two steps and the tortoise one.
* If the hare ever laps the tortoise, there must be a loop. * If the hare ever laps the tortoise, there must be a loop.
@ -4182,14 +4202,16 @@ function wp_find_hierarchy_loop( $callback, $start, $start_parent, $callback_arg
* @since 3.1.0 * @since 3.1.0
* @access private * @access private
* *
* @param callback $callback function that accepts ( ID, callback_arg, ... ) and outputs parent_ID * @param callback $callback Function that accepts ( ID, callback_arg, ... ) and outputs parent_ID.
* @param int $start The ID to start the loop check at * @param int $start The ID to start the loop check at.
* @param array $override an array of ( ID => parent_ID, ... ) to use instead of $callback * @param array $override Optional. An array of ( ID => parent_ID, ... ) to use instead of $callback.
* @param array $callback_args optional additional arguments to send to $callback * Default empty array.
* @param bool $_return_loop Return loop members or just detect presence of loop? * @param array $callback_args Optional. Additional arguments to send to $callback. Default empty array.
* Only set to true if you already know the given $start is part of a loop * @param bool $_return_loop Optional. Return loop members or just detect presence of loop? Only set
* (otherwise the returned array might include branches) * to true if you already know the given $start is part of a loop (otherwise
* @return mixed scalar ID of some arbitrary member of the loop, or array of IDs of all members of loop if $_return_loop * the returned array might include branches). Default false.
* @return mixed Scalar ID of some arbitrary member of the loop, or array of IDs of all members of loop if
* $_return_loop
*/ */
function wp_find_hierarchy_loop_tortoise_hare( $callback, $start, $override = array(), $callback_args = array(), $_return_loop = false ) { function wp_find_hierarchy_loop_tortoise_hare( $callback, $start, $override = array(), $callback_args = array(), $_return_loop = false ) {
$tortoise = $hare = $evanescent_hare = $start; $tortoise = $hare = $evanescent_hare = $start;
@ -4221,10 +4243,9 @@ function wp_find_hierarchy_loop_tortoise_hare( $callback, $start, $override = ar
/** /**
* Send a HTTP header to limit rendering of pages to same origin iframes. * Send a HTTP header to limit rendering of pages to same origin iframes.
* *
* @link https://developer.mozilla.org/en/the_x-frame-options_response_header
*
* @since 3.1.3 * @since 3.1.3
* @return none *
* @see https://developer.mozilla.org/en/the_x-frame-options_response_header
*/ */
function send_frame_options_header() { function send_frame_options_header() {
@header( 'X-Frame-Options: SAMEORIGIN' ); @header( 'X-Frame-Options: SAMEORIGIN' );
@ -4234,10 +4255,11 @@ function send_frame_options_header() {
* Retrieve a list of protocols to allow in HTML attributes. * Retrieve a list of protocols to allow in HTML attributes.
* *
* @since 3.3.0 * @since 3.3.0
*
* @see wp_kses() * @see wp_kses()
* @see esc_url() * @see esc_url()
* *
* @return array Array of allowed protocols * @return array Array of allowed protocols.
*/ */
function wp_allowed_protocols() { function wp_allowed_protocols() {
static $protocols; static $protocols;
@ -4259,15 +4281,21 @@ function wp_allowed_protocols() {
} }
/** /**
* Return a comma separated string of functions that have been called to get to the current point in code. * Return a comma-separated string of functions that have been called to get
* to the current point in code.
* *
* @link http://core.trac.wordpress.org/ticket/19589
* @since 3.4.0 * @since 3.4.0
* *
* @param string $ignore_class A class to ignore all function calls within - useful when you want to just give info about the callee * @see http://core.trac.wordpress.org/ticket/19589
* @param int $skip_frames A number of stack frames to skip - useful for unwinding back to the source of the issue *
* @param bool $pretty Whether or not you want a comma separated string or raw array returned * @param string $ignore_class Optional. A class to ignore all function calls within - useful
* @return string|array Either a string containing a reversed comma separated trace or an array of individual calls. * when you want to just give info about the callee. Default null.
* @param int $skip_frames Optional. A number of stack frames to skip - useful for unwinding
* back to the source of the issue. Default 0.
* @param bool $pretty Optional. Whether or not you want a comma separated string or raw
* array returned. Default true.
* @return string|array Either a string containing a reversed comma separated trace or an array
* of individual calls.
*/ */
function wp_debug_backtrace_summary( $ignore_class = null, $skip_frames = 0, $pretty = true ) { function wp_debug_backtrace_summary( $ignore_class = null, $skip_frames = 0, $pretty = true ) {
if ( version_compare( PHP_VERSION, '5.2.5', '>=' ) ) if ( version_compare( PHP_VERSION, '5.2.5', '>=' ) )
@ -4304,14 +4332,15 @@ function wp_debug_backtrace_summary( $ignore_class = null, $skip_frames = 0, $pr
} }
/** /**
* Retrieve ids that are not already present in the cache * Retrieve ids that are not already present in the cache.
* *
* @since 3.4.0 * @since 3.4.0
* @access private
* *
* @param array $object_ids ID list * @param array $object_ids ID list.
* @param string $cache_key The cache bucket to check against * @param string $cache_key The cache bucket to check against.
* *
* @return array * @return array List of ids not present in the cache.
*/ */
function _get_non_cached_ids( $object_ids, $cache_key ) { function _get_non_cached_ids( $object_ids, $cache_key ) {
$clean = array(); $clean = array();
@ -4331,7 +4360,7 @@ function _get_non_cached_ids( $object_ids, $cache_key ) {
* @since 3.4.0 * @since 3.4.0
* @access private * @access private
* *
* @return bool true|false * @return bool true|false Whether the device is able to upload files.
*/ */
function _device_can_upload() { function _device_can_upload() {
if ( ! wp_is_mobile() ) if ( ! wp_is_mobile() )
@ -4351,8 +4380,8 @@ function _device_can_upload() {
/** /**
* Test if a given path is a stream URL * Test if a given path is a stream URL
* *
* @param string $path The resource path or URL * @param string $path The resource path or URL.
* @return bool True if the path is a stream URL * @return bool True if the path is a stream URL.
*/ */
function wp_is_stream( $path ) { function wp_is_stream( $path ) {
$wrappers = stream_get_wrappers(); $wrappers = stream_get_wrappers();
@ -4411,6 +4440,9 @@ function wp_auth_check_load() {
/** /**
* Filter whether to load the authentication check. * Filter whether to load the authentication check.
* *
* Passing a falsey value to the filter will effectively short-circuit
* loading the authentication check.
*
* @since 3.6.0 * @since 3.6.0
* *
* @param bool $show Whether to load the authentication check. * @param bool $show Whether to load the authentication check.
@ -4487,17 +4519,20 @@ function wp_auth_check( $response ) {
} }
/** /**
* Return RegEx body to liberally match an opening HTML tag that: * Return RegEx body to liberally match an opening HTML tag.
*
* Matches an opening HTML tag that:
* 1. Is self-closing or * 1. Is self-closing or
* 2. Has no body but has a closing tag of the same name or * 2. Has no body but has a closing tag of the same name or
* 3. Contains a body and a closing tag of the same name * 3. Contains a body and a closing tag of the same name
* *
* Note: this RegEx does not balance inner tags and does not attempt to produce valid HTML * Note: this RegEx does not balance inner tags and does not attempt
* to produce valid HTML
* *
* @since 3.6.0 * @since 3.6.0
* *
* @param string $tag An HTML tag name. Example: 'video' * @param string $tag An HTML tag name. Example: 'video'.
* @return string * @return string Tag RegEx.
*/ */
function get_tag_regex( $tag ) { function get_tag_regex( $tag ) {
if ( empty( $tag ) ) if ( empty( $tag ) )
@ -4506,14 +4541,16 @@ function get_tag_regex( $tag ) {
} }
/** /**
* Return a canonical form of the provided charset appropriate for passing to PHP * Retrieve a canonical form of the provided charset appropriate for passing to PHP
* functions such as htmlspecialchars() and charset html attributes. * functions such as htmlspecialchars() and charset html attributes.
* *
* @link http://core.trac.wordpress.org/ticket/23688
* @since 3.6.0 * @since 3.6.0
* @access private
* *
* @param string A charset name * @see http://core.trac.wordpress.org/ticket/23688
* @return string The canonical form of the charset *
* @param string $charset A charset name.
* @return string The canonical form of the charset.
*/ */
function _canonical_charset( $charset ) { function _canonical_charset( $charset ) {
if ( 'UTF-8' === $charset || 'utf-8' === $charset || 'utf8' === $charset || if ( 'UTF-8' === $charset || 'utf-8' === $charset || 'utf8' === $charset ||
@ -4528,22 +4565,27 @@ function _canonical_charset( $charset ) {
} }
/** /**
* Sets the mbstring internal encoding to a binary safe encoding when func_overload is enabled. * Set the mbstring internal encoding to a binary safe encoding when func_overload
* is enabled.
* *
* When mbstring.func_overload is in use for multi-byte encodings, the results from strlen() and * When mbstring.func_overload is in use for multi-byte encodings, the results from
* similar functions respect the utf8 characters, causing binary data to return incorrect lengths. * strlen() and similar functions respect the utf8 characters, causing binary data
* to return incorrect lengths.
* *
* This function overrides the mbstring encoding to a binary-safe encoding, and resets it to the * This function overrides the mbstring encoding to a binary-safe encoding, and
* users expected encoding afterwards through the `reset_mbstring_encoding` function. * resets it to the users expected encoding afterwards through the
* `reset_mbstring_encoding` function.
* *
* It is safe to recursively call this function, however each `mbstring_binary_safe_encoding()` * It is safe to recursively call this function, however each
* call must be followed up with an equal number of `reset_mbstring_encoding()` calls. * `mbstring_binary_safe_encoding()` call must be followed up with an equal number
* * of `reset_mbstring_encoding()` calls.
* @see reset_mbstring_encoding()
* *
* @since 3.7.0 * @since 3.7.0
* *
* @param bool $reset Whether to reset the encoding back to a previously-set encoding. * @see reset_mbstring_encoding()
*
* @param bool $reset Optional. Whether to reset the encoding back to a previously-set encoding.
* Default false.
*/ */
function mbstring_binary_safe_encoding( $reset = false ) { function mbstring_binary_safe_encoding( $reset = false ) {
static $encodings = array(); static $encodings = array();
@ -4568,7 +4610,7 @@ function mbstring_binary_safe_encoding( $reset = false ) {
} }
/** /**
* Resets the mbstring internal encoding to a users previously set encoding. * Reset the mbstring internal encoding to a users previously set encoding.
* *
* @see mbstring_binary_safe_encoding() * @see mbstring_binary_safe_encoding()
* *
@ -4579,12 +4621,12 @@ function reset_mbstring_encoding() {
} }
/** /**
* Alternative to filter_var( $var, FILTER_VALIDATE_BOOLEAN ) * Alternative to filter_var( $var, FILTER_VALIDATE_BOOLEAN ).
* *
* @since 4.0.0 * @since 4.0.0
* *
* @param mixed $var * @param mixed $var Boolean value to validate.
* @return boolean * @return bool Whether the value is validated.
*/ */
function wp_validate_boolean( $var ) { function wp_validate_boolean( $var ) {
if ( is_bool( $var ) ) { if ( is_bool( $var ) ) {