<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head><meta http-equiv="content-type" content="text/html; charset=utf-8" />
<title>[29011] trunk/src/wp-includes/functions.php: General inline documentation improvements in wp-includes/functions.php.</title>
</head>
<body>
<style type="text/css"><!--
#msg dl.meta { border: 1px #006 solid; background: #369; padding: 6px; color: #fff; }
#msg dl.meta dt { float: left; width: 6em; font-weight: bold; }
#msg dt:after { content:':';}
#msg dl, #msg dt, #msg ul, #msg li, #header, #footer, #logmsg { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; }
#msg dl a { font-weight: bold}
#msg dl a:link { color:#fc3; }
#msg dl a:active { color:#ff0; }
#msg dl a:visited { color:#cc6; }
h3 { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; font-weight: bold; }
#msg pre { overflow: auto; background: #ffc; border: 1px #fa0 solid; padding: 6px; }
#logmsg { background: #ffc; border: 1px #fa0 solid; padding: 1em 1em 0 1em; }
#logmsg p, #logmsg pre, #logmsg blockquote { margin: 0 0 1em 0; }
#logmsg p, #logmsg li, #logmsg dt, #logmsg dd { line-height: 14pt; }
#logmsg h1, #logmsg h2, #logmsg h3, #logmsg h4, #logmsg h5, #logmsg h6 { margin: .5em 0; }
#logmsg h1:first-child, #logmsg h2:first-child, #logmsg h3:first-child, #logmsg h4:first-child, #logmsg h5:first-child, #logmsg h6:first-child { margin-top: 0; }
#logmsg ul, #logmsg ol { padding: 0; list-style-position: inside; margin: 0 0 0 1em; }
#logmsg ul { text-indent: -1em; padding-left: 1em; }#logmsg ol { text-indent: -1.5em; padding-left: 1.5em; }
#logmsg > ul, #logmsg > ol { margin: 0 0 1em 0; }
#logmsg pre { background: #eee; padding: 1em; }
#logmsg blockquote { border: 1px solid #fa0; border-left-width: 10px; padding: 1em 1em 0 1em; background: white;}
#logmsg dl { margin: 0; }
#logmsg dt { font-weight: bold; }
#logmsg dd { margin: 0; padding: 0 0 0.5em 0; }
#logmsg dd:before { content:'\00bb';}
#logmsg table { border-spacing: 0px; border-collapse: collapse; border-top: 4px solid #fa0; border-bottom: 1px solid #fa0; background: #fff; }
#logmsg table th { text-align: left; font-weight: normal; padding: 0.2em 0.5em; border-top: 1px dotted #fa0; }
#logmsg table td { text-align: right; border-top: 1px dotted #fa0; padding: 0.2em 0.5em; }
#logmsg table thead th { text-align: center; border-bottom: 1px solid #fa0; }
#logmsg table th.Corner { text-align: left; }
#logmsg hr { border: none 0; border-top: 2px dashed #fa0; height: 1px; }
#header, #footer { color: #fff; background: #636; border: 1px #300 solid; padding: 6px; }
#patch { width: 100%; }
#patch h4 {font-family: verdana,arial,helvetica,sans-serif;font-size:10pt;padding:8px;background:#369;color:#fff;margin:0;}
#patch .propset h4, #patch .binary h4 {margin:0;}
#patch pre {padding:0;line-height:1.2em;margin:0;}
#patch .diff {width:100%;background:#eee;padding: 0 0 10px 0;overflow:auto;}
#patch .propset .diff, #patch .binary .diff {padding:10px 0;}
#patch span {display:block;padding:0 10px;}
#patch .modfile, #patch .addfile, #patch .delfile, #patch .propset, #patch .binary, #patch .copfile {border:1px solid #ccc;margin:10px 0;}
#patch ins {background:#dfd;text-decoration:none;display:block;padding:0 10px;}
#patch del {background:#fdd;text-decoration:none;display:block;padding:0 10px;}
#patch .lines, .info {color:#888;background:#fff;}
--></style>
<div id="msg">
<dl class="meta">
<dt>Revision</dt> <dd><a href="http://core.trac.wordpress.org/changeset/29011">29011</a></dd>
<dt>Author</dt> <dd>DrewAPicture</dd>
<dt>Date</dt> <dd>2014-07-07 06:18:05 +0000 (Mon, 07 Jul 2014)</dd>
</dl>
<h3>Log Message</h3>
<pre>General inline documentation improvements in wp-includes/functions.php.
Final run. Fixes <a href="http://core.trac.wordpress.org/ticket/26185">#26185</a>.</pre>
<h3>Modified Paths</h3>
<ul>
<li><a href="#trunksrcwpincludesfunctionsphp">trunk/src/wp-includes/functions.php</a></li>
</ul>
</div>
<div id="patch">
<h3>Diff</h3>
<a id="trunksrcwpincludesfunctionsphp"></a>
<div class="modfile"><h4>Modified: trunk/src/wp-includes/functions.php (29010 => 29011)</h4>
<pre class="diff"><span>
<span class="info">--- trunk/src/wp-includes/functions.php 2014-07-07 01:20:53 UTC (rev 29010)
+++ trunk/src/wp-includes/functions.php 2014-07-07 06:18:05 UTC (rev 29011)
</span><span class="lines">@@ -674,8 +674,9 @@
</span><span class="cx"> * From php.net (modified by Mark Jaquith to behave like the native PHP5 function).
</span><span class="cx"> *
</span><span class="cx"> * @since 3.2.0
</span><ins>+ * @access private
</ins><span class="cx"> *
</span><del>- * @link http://us1.php.net/manual/en/function.http-build-query.php
</del><ins>+ * @see http://us1.php.net/manual/en/function.http-build-query.php
</ins><span class="cx"> *
</span><span class="cx"> * @param array|object $data An array or object of data. Converted to array.
</span><span class="cx"> * @param string $prefix Optional. Numeric index. If set, start parameter numbering with it.
</span><span class="lines">@@ -3145,19 +3146,19 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Converts value to nonnegative integer.
</del><ins>+ * Convert a value to non-negative integer.
</ins><span class="cx"> *
</span><span class="cx"> * @since 2.5.0
</span><span class="cx"> *
</span><del>- * @param mixed $maybeint Data you wish to have converted to a nonnegative integer
- * @return int An nonnegative integer
</del><ins>+ * @param mixed $maybeint Data you wish to have converted to a non-negative integer.
+ * @return int A non-negative integer.
</ins><span class="cx"> */
</span><span class="cx"> function absint( $maybeint ) {
</span><span class="cx"> return abs( intval( $maybeint ) );
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Marks a function as deprecated and informs when it has been used.
</del><ins>+ * Mark a function as deprecated and informs when it has been used.
</ins><span class="cx"> *
</span><span class="cx"> * There is a hook deprecated_function_run that will be called that can be used
</span><span class="cx"> * to get the backtrace up to what file and function called the deprecated
</span><span class="lines">@@ -3170,9 +3171,9 @@
</span><span class="cx"> * @since 2.5.0
</span><span class="cx"> * @access private
</span><span class="cx"> *
</span><del>- * @param string $function The function that was called
- * @param string $version The version of WordPress that deprecated the function
- * @param string $replacement Optional. The function that should have been called
</del><ins>+ * @param string $function The function that was called.
+ * @param string $version The version of WordPress that deprecated the function.
+ * @param string $replacement Optional. The function that should have been called. Default null.
</ins><span class="cx"> */
</span><span class="cx"> function _deprecated_function( $function, $version, $replacement = null ) {
</span><span class="cx">
</span><span class="lines">@@ -3210,7 +3211,7 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Marks a file as deprecated and informs when it has been used.
</del><ins>+ * Marks a file as deprecated and inform when it has been used.
</ins><span class="cx"> *
</span><span class="cx"> * There is a hook deprecated_file_included that will be called that can be used
</span><span class="cx"> * to get the backtrace up to what file and function included the deprecated
</span><span class="lines">@@ -3223,10 +3224,11 @@
</span><span class="cx"> * @since 2.5.0
</span><span class="cx"> * @access private
</span><span class="cx"> *
</span><del>- * @param string $file The file that was included
- * @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 $message Optional. A message regarding the change
</del><ins>+ * @param string $file The file that was included.
+ * @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.
+ * Default null.
+ * @param string $message Optional. A message regarding the change. Default empty.
</ins><span class="cx"> */
</span><span class="cx"> function _deprecated_file( $file, $version, $replacement = null, $message = '' ) {
</span><span class="cx">
</span><span class="lines">@@ -3265,7 +3267,7 @@
</span><span class="cx"> }
</span><span class="cx"> }
</span><span class="cx"> /**
</span><del>- * Marks a function argument as deprecated and informs when it has been used.
</del><ins>+ * Mark a function argument as deprecated and inform when it has been used.
</ins><span class="cx"> *
</span><span class="cx"> * This function is to be used whenever a deprecated function argument is used.
</span><span class="cx"> * Before this function is called, the argument must be checked for whether it was
</span><span class="lines">@@ -3285,9 +3287,9 @@
</span><span class="cx"> * @since 3.0.0
</span><span class="cx"> * @access private
</span><span class="cx"> *
</span><del>- * @param string $function The function that was called
- * @param string $version The version of WordPress that deprecated the argument used
- * @param string $message Optional. A message regarding the change.
</del><ins>+ * @param string $function The function that was called.
+ * @param string $version The version of WordPress that deprecated the argument used.
+ * @param string $message Optional. A message regarding the change. Default null.
</ins><span class="cx"> */
</span><span class="cx"> function _deprecated_argument( $function, $version, $message = null ) {
</span><span class="cx">
</span><span class="lines">@@ -3325,7 +3327,7 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Marks something as being incorrectly called.
</del><ins>+ * Mark something as being incorrectly called.
</ins><span class="cx"> *
</span><span class="cx"> * There is a hook doing_it_wrong_run that will be called that can be used
</span><span class="cx"> * to get the backtrace up to what file and function called the deprecated
</span><span class="lines">@@ -3337,8 +3339,8 @@
</span><span class="cx"> * @access private
</span><span class="cx"> *
</span><span class="cx"> * @param string $function The function that was called.
</span><del>- * @param string $message A message explaining what has been done incorrectly.
- * @param string $version The version of WordPress where the message was added.
</del><ins>+ * @param string $message A message explaining what has been done incorrectly.
+ * @param string $version The version of WordPress where the message was added.
</ins><span class="cx"> */
</span><span class="cx"> function _doing_it_wrong( $function, $message, $version ) {
</span><span class="cx">
</span><span class="lines">@@ -3378,7 +3380,7 @@
</span><span class="cx"> *
</span><span class="cx"> * @since 2.5.0
</span><span class="cx"> *
</span><del>- * @return bool Whether the server is running lighttpd < 1.5.0
</del><ins>+ * @return bool Whether the server is running lighttpd < 1.5.0.
</ins><span class="cx"> */
</span><span class="cx"> function is_lighttpd_before_150() {
</span><span class="cx"> $server_parts = explode( '/', isset( $_SERVER['SERVER_SOFTWARE'] )? $_SERVER['SERVER_SOFTWARE'] : '' );
</span><span class="lines">@@ -3391,9 +3393,9 @@
</span><span class="cx"> *
</span><span class="cx"> * @since 2.5.0
</span><span class="cx"> *
</span><del>- * @param string $mod e.g. mod_rewrite
- * @param bool $default The default return value if the module is not found
- * @return bool
</del><ins>+ * @param string $mod The module, e.g. mod_rewrite.
+ * @param bool $default Optional. The default return value if the module is not found. Default false.
+ * @return bool Whether the specified module is loaded.
</ins><span class="cx"> */
</span><span class="cx"> function apache_mod_loaded($mod, $default = false) {
</span><span class="cx"> global $is_apache;
</span><span class="lines">@@ -3420,7 +3422,7 @@
</span><span class="cx"> *
</span><span class="cx"> * @since 2.8.0
</span><span class="cx"> *
</span><del>- * @return bool
</del><ins>+ * @return bool Whether IIS7 supports permalinks.
</ins><span class="cx"> */
</span><span class="cx"> function iis7_supports_permalinks() {
</span><span class="cx"> global $is_iis7;
</span><span class="lines">@@ -3504,7 +3506,7 @@
</span><span class="cx"> * @since 4.0.0
</span><span class="cx"> *
</span><span class="cx"> * @param string $url The URL
</span><del>- * @return boolean True if the given URL uses https, false if not (or if the URL is not valid).
</del><ins>+ * @return bool True if the given URL uses https, false if not (or if the URL is not valid).
</ins><span class="cx"> */
</span><span class="cx"> function is_https_url( $url ) {
</span><span class="cx"> return ( 'https' === parse_url( $url, PHP_URL_SCHEME ) );
</span><span class="lines">@@ -3515,7 +3517,9 @@
</span><span class="cx"> *
</span><span class="cx"> * @since 2.6.0
</span><span class="cx"> *
</span><del>- * @param string|bool $force Optional.
</del><ins>+ * @see force_ssl_admin()
+ *
+ * @param string|bool $force Optional Whether to force SSL login. Default null.
</ins><span class="cx"> * @return bool True if forced, false if not forced.
</span><span class="cx"> */
</span><span class="cx"> function force_ssl_login( $force = null ) {
</span><span class="lines">@@ -3527,7 +3531,7 @@
</span><span class="cx"> *
</span><span class="cx"> * @since 2.6.0
</span><span class="cx"> *
</span><del>- * @param string|bool $force
</del><ins>+ * @param string|bool $force Optional. Whether to force SSL in admin screens. Default null.
</ins><span class="cx"> * @return bool True if forced, false if not forced.
</span><span class="cx"> */
</span><span class="cx"> function force_ssl_admin( $force = null ) {
</span><span class="lines">@@ -3550,7 +3554,7 @@
</span><span class="cx"> *
</span><span class="cx"> * @since 2.6.0
</span><span class="cx"> *
</span><del>- * @return string
</del><ins>+ * @return string The guessed URL.
</ins><span class="cx"> */
</span><span class="cx"> function wp_guess_url() {
</span><span class="cx"> if ( defined('WP_SITEURL') && '' != WP_SITEURL ) {
</span><span class="lines">@@ -3618,16 +3622,16 @@
</span><span class="cx"> /**
</span><span class="cx"> * Suspend cache invalidation.
</span><span class="cx"> *
</span><del>- * Turns cache invalidation on and off. Useful during imports where you don't wont to do invalidations
- * every time a post is inserted. Callers must be sure that what they are doing won't lead to an inconsistent
- * cache when invalidation is suspended.
</del><ins>+ * Turns cache invalidation on and off. Useful during imports where you don't wont to do
+ * invalidations every time a post is inserted. Callers must be sure that what they are
+ * doing won't lead to an inconsistent cache when invalidation is suspended.
</ins><span class="cx"> *
</span><span class="cx"> * @since 2.7.0
</span><span class="cx"> *
</span><del>- * @param bool $suspend Whether to suspend or enable cache invalidation
- * @return bool The current suspend setting
</del><ins>+ * @param bool $suspend Optional. Whether to suspend or enable cache invalidation. Default true.
+ * @return bool The current suspend setting.
</ins><span class="cx"> */
</span><del>-function wp_suspend_cache_invalidation($suspend = true) {
</del><ins>+function wp_suspend_cache_invalidation( $suspend = true ) {
</ins><span class="cx"> global $_wp_suspend_cache_invalidation;
</span><span class="cx">
</span><span class="cx"> $current_suspend = $_wp_suspend_cache_invalidation;
</span><span class="lines">@@ -3636,12 +3640,14 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Whether a site is the main site of the current network.
</del><ins>+ * Determine whether a site is the main site of the current network.
</ins><span class="cx"> *
</span><span class="cx"> * @since 3.0.0
</span><span class="cx"> *
</span><span class="cx"> * @param int $site_id Optional. Site ID to test. Defaults to current site.
</span><del>- * @return bool True if $site_id is the main site of the network, or if not running multisite.
</del><ins>+ * Defaults to current site.
+ * @return bool True if $site_id is the main site of the network, or if not
+ * running Multisite.
</ins><span class="cx"> */
</span><span class="cx"> function is_main_site( $site_id = null ) {
</span><span class="cx"> // This is the current network's information; 'site' is old terminology.
</span><span class="lines">@@ -3657,12 +3663,12 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Whether a network is the main network of the multisite install.
</del><ins>+ * Determine whether a network is the main network of the Multisite install.
</ins><span class="cx"> *
</span><span class="cx"> * @since 3.7.0
</span><span class="cx"> *
</span><span class="cx"> * @param int $network_id Optional. Network ID to test. Defaults to current network.
</span><del>- * @return bool True if $network_id is the main network, or if not running multisite.
</del><ins>+ * @return bool True if $network_id is the main network, or if not running Multisite.
</ins><span class="cx"> */
</span><span class="cx"> function is_main_network( $network_id = null ) {
</span><span class="cx"> global $wpdb;
</span><span class="lines">@@ -3694,12 +3700,11 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Whether global terms are enabled.
</del><ins>+ * Determine whether global terms are enabled.
</ins><span class="cx"> *
</span><del>- *
</del><span class="cx"> * @since 3.0.0
</span><span class="cx"> *
</span><del>- * @return bool True if multisite and global terms enabled
</del><ins>+ * @return bool True if multisite and global terms enabled.
</ins><span class="cx"> */
</span><span class="cx"> function global_terms_enabled() {
</span><span class="cx"> if ( ! is_multisite() )
</span><span class="lines">@@ -3734,7 +3739,7 @@
</span><span class="cx"> *
</span><span class="cx"> * @since 2.8.0
</span><span class="cx"> *
</span><del>- * @return float|bool
</del><ins>+ * @return float|bool Timezone GMT offset, false otherwise.
</ins><span class="cx"> */
</span><span class="cx"> function wp_timezone_override_offset() {
</span><span class="cx"> if ( !$timezone_string = get_option( 'timezone_string' ) ) {
</span><span class="lines">@@ -3753,6 +3758,7 @@
</span><span class="cx"> * Sort-helper for timezones.
</span><span class="cx"> *
</span><span class="cx"> * @since 2.9.0
</span><ins>+ * @access private
</ins><span class="cx"> *
</span><span class="cx"> * @param array $a
</span><span class="cx"> * @param array $b
</span><span class="lines">@@ -3797,11 +3803,11 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Gives a nicely formatted list of timezone strings.
</del><ins>+ * Gives a nicely-formatted list of timezone strings.
</ins><span class="cx"> *
</span><span class="cx"> * @since 2.9.0
</span><span class="cx"> *
</span><del>- * @param string $selected_zone Selected Zone
</del><ins>+ * @param string $selected_zone Selected timezone.
</ins><span class="cx"> * @return string
</span><span class="cx"> */
</span><span class="cx"> function wp_timezone_choice( $selected_zone ) {
</span><span class="lines">@@ -3927,19 +3933,22 @@
</span><span class="cx">
</span><span class="cx"> /**
</span><span class="cx"> * Strip close comment and close php tags from file headers used by WP.
</span><del>- * See http://core.trac.wordpress.org/ticket/8497
</del><span class="cx"> *
</span><span class="cx"> * @since 2.8.0
</span><ins>+ * @access private
</ins><span class="cx"> *
</span><del>- * @param string $str
</del><ins>+ * @see http://core.trac.wordpress.org/ticket/8497
+ *
+ * @param string $str Header comment to clean up.
</ins><span class="cx"> * @return string
</span><span class="cx"> */
</span><del>-function _cleanup_header_comment($str) {
</del><ins>+function _cleanup_header_comment( $str ) {
</ins><span class="cx"> return trim(preg_replace("/\s*(?:\*\/|\?>).*/", '', $str));
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Permanently deletes posts, pages, attachments, and comments which have been in the trash for EMPTY_TRASH_DAYS.
</del><ins>+ * Permanently delete posts, pages, attachments, and comments which have been
+ * in the trash for EMPTY_TRASH_DAYS.
</ins><span class="cx"> *
</span><span class="cx"> * @since 2.9.0
</span><span class="cx"> */
</span><span class="lines">@@ -3996,9 +4005,10 @@
</span><span class="cx"> * @see http://codex.wordpress.org/File_Header
</span><span class="cx"> *
</span><span class="cx"> * @since 2.9.0
</span><del>- * @param string $file Path to the file
- * @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"
</del><ins>+ * @param string $file Path to the file.
+ * @param array $default_headers List of headers, in the format array('HeaderKey' => 'Header Name').
+ * @param string $context Optional. If specified adds filter hook "extra_{$context}_headers".
+ * Default empty.
</ins><span class="cx"> */
</span><span class="cx"> function get_file_data( $file, $default_headers, $context = '' ) {
</span><span class="cx"> // We don't need to write to the file, so just open for reading.
</span><span class="lines">@@ -4046,8 +4056,10 @@
</span><span class="cx"> * Useful for returning true to filters easily.
</span><span class="cx"> *
</span><span class="cx"> * @since 3.0.0
</span><ins>+ *
</ins><span class="cx"> * @see __return_false()
</span><del>- * @return bool true
</del><ins>+ *
+ * @return bool True.
</ins><span class="cx"> */
</span><span class="cx"> function __return_true() {
</span><span class="cx"> return true;
</span><span class="lines">@@ -4059,8 +4071,10 @@
</span><span class="cx"> * Useful for returning false to filters easily.
</span><span class="cx"> *
</span><span class="cx"> * @since 3.0.0
</span><ins>+ *
</ins><span class="cx"> * @see __return_true()
</span><del>- * @return bool false
</del><ins>+ *
+ * @return bool False.
</ins><span class="cx"> */
</span><span class="cx"> function __return_false() {
</span><span class="cx"> return false;
</span><span class="lines">@@ -4072,7 +4086,8 @@
</span><span class="cx"> * Useful for returning 0 to filters easily.
</span><span class="cx"> *
</span><span class="cx"> * @since 3.0.0
</span><del>- * @return int 0
</del><ins>+ *
+ * @return int 0.
</ins><span class="cx"> */
</span><span class="cx"> function __return_zero() {
</span><span class="cx"> return 0;
</span><span class="lines">@@ -4084,7 +4099,8 @@
</span><span class="cx"> * Useful for returning an empty array to filters easily.
</span><span class="cx"> *
</span><span class="cx"> * @since 3.0.0
</span><del>- * @return array Empty array
</del><ins>+ *
+ * @return array Empty array.
</ins><span class="cx"> */
</span><span class="cx"> function __return_empty_array() {
</span><span class="cx"> return array();
</span><span class="lines">@@ -4096,7 +4112,8 @@
</span><span class="cx"> * Useful for returning null to filters easily.
</span><span class="cx"> *
</span><span class="cx"> * @since 3.4.0
</span><del>- * @return null
</del><ins>+ *
+ * @return null Null value.
</ins><span class="cx"> */
</span><span class="cx"> function __return_null() {
</span><span class="cx"> return null;
</span><span class="lines">@@ -4108,8 +4125,10 @@
</span><span class="cx"> * Useful for returning an empty string to filters easily.
</span><span class="cx"> *
</span><span class="cx"> * @since 3.7.0
</span><ins>+ *
</ins><span class="cx"> * @see __return_null()
</span><del>- * @return string Empty string
</del><ins>+ *
+ * @return string Empty string.
</ins><span class="cx"> */
</span><span class="cx"> function __return_empty_string() {
</span><span class="cx"> return '';
</span><span class="lines">@@ -4118,23 +4137,23 @@
</span><span class="cx"> /**
</span><span class="cx"> * Send a HTTP header to disable content type sniffing in browsers which support it.
</span><span class="cx"> *
</span><del>- * @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
</del><ins>+ * @since 3.0.0
</ins><span class="cx"> *
</span><del>- * @since 3.0.0
- * @return none
</del><ins>+ * @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
</ins><span class="cx"> */
</span><span class="cx"> function send_nosniff_header() {
</span><span class="cx"> @header( 'X-Content-Type-Options: nosniff' );
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Returns a MySQL expression for selecting the week number based on the start_of_week option.
</del><ins>+ * Return a MySQL expression for selecting the week number based on the start_of_week option.
</ins><span class="cx"> *
</span><span class="cx"> * @internal
</span><span class="cx"> * @since 3.0.0
</span><del>- * @param string $column
- * @return string
</del><ins>+ *
+ * @param string $column Database column.
+ * @return string SQL clause.
</ins><span class="cx"> */
</span><span class="cx"> function _wp_mysql_week( $column ) {
</span><span class="cx"> switch ( $start_of_week = (int) get_option( 'start_of_week' ) ) {
</span><span class="lines">@@ -4153,16 +4172,17 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Finds hierarchy loops using a callback function that maps object IDs to parent IDs.
</del><ins>+ * Find hierarchy loops using a callback function that maps object IDs to parent IDs.
</ins><span class="cx"> *
</span><span class="cx"> * @since 3.1.0
</span><span class="cx"> * @access private
</span><span class="cx"> *
</span><del>- * @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_parent the parent_ID of $start to use instead of calling $callback( $start ). Use null to always use $callback
- * @param array $callback_args optional additional arguments to send to $callback
- * @return array IDs of all members of loop
</del><ins>+ * @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_parent The parent_ID of $start to use instead of calling $callback( $start ).
+ * Use null to always use $callback
+ * @param array $callback_args Optional. Additional arguments to send to $callback.
+ * @return array IDs of all members of loop.
</ins><span class="cx"> */
</span><span class="cx"> function wp_find_hierarchy_loop( $callback, $start, $start_parent, $callback_args = array() ) {
</span><span class="cx"> $override = is_null( $start_parent ) ? array() : array( $start => $start_parent );
</span><span class="lines">@@ -4174,7 +4194,7 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Uses the "The Tortoise and the Hare" algorithm to detect loops.
</del><ins>+ * Use the "The Tortoise and the Hare" algorithm to detect loops.
</ins><span class="cx"> *
</span><span class="cx"> * For every step of the algorithm, the hare takes two steps and the tortoise one.
</span><span class="cx"> * If the hare ever laps the tortoise, there must be a loop.
</span><span class="lines">@@ -4182,14 +4202,16 @@
</span><span class="cx"> * @since 3.1.0
</span><span class="cx"> * @access private
</span><span class="cx"> *
</span><del>- * @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 array $override an array of ( ID => parent_ID, ... ) to use instead of $callback
- * @param array $callback_args optional additional arguments to send to $callback
- * @param bool $_return_loop Return loop members or just detect presence of loop?
- * Only set to true if you already know the given $start is part of a loop
- * (otherwise the returned array might include branches)
- * @return mixed scalar ID of some arbitrary member of the loop, or array of IDs of all members of loop if $_return_loop
</del><ins>+ * @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 array $override Optional. An array of ( ID => parent_ID, ... ) to use instead of $callback.
+ * Default empty array.
+ * @param array $callback_args Optional. Additional arguments to send to $callback. Default empty array.
+ * @param bool $_return_loop Optional. Return loop members or just detect presence of loop? Only set
+ * to true if you already know the given $start is part of a loop (otherwise
+ * 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
</ins><span class="cx"> */
</span><span class="cx"> function wp_find_hierarchy_loop_tortoise_hare( $callback, $start, $override = array(), $callback_args = array(), $_return_loop = false ) {
</span><span class="cx"> $tortoise = $hare = $evanescent_hare = $start;
</span><span class="lines">@@ -4221,10 +4243,9 @@
</span><span class="cx"> /**
</span><span class="cx"> * Send a HTTP header to limit rendering of pages to same origin iframes.
</span><span class="cx"> *
</span><del>- * @link https://developer.mozilla.org/en/the_x-frame-options_response_header
</del><ins>+ * @since 3.1.3
</ins><span class="cx"> *
</span><del>- * @since 3.1.3
- * @return none
</del><ins>+ * @see https://developer.mozilla.org/en/the_x-frame-options_response_header
</ins><span class="cx"> */
</span><span class="cx"> function send_frame_options_header() {
</span><span class="cx"> @header( 'X-Frame-Options: SAMEORIGIN' );
</span><span class="lines">@@ -4234,10 +4255,11 @@
</span><span class="cx"> * Retrieve a list of protocols to allow in HTML attributes.
</span><span class="cx"> *
</span><span class="cx"> * @since 3.3.0
</span><ins>+ *
</ins><span class="cx"> * @see wp_kses()
</span><span class="cx"> * @see esc_url()
</span><span class="cx"> *
</span><del>- * @return array Array of allowed protocols
</del><ins>+ * @return array Array of allowed protocols.
</ins><span class="cx"> */
</span><span class="cx"> function wp_allowed_protocols() {
</span><span class="cx"> static $protocols;
</span><span class="lines">@@ -4259,15 +4281,21 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Return a comma separated string of functions that have been called to get to the current point in code.
</del><ins>+ * Return a comma-separated string of functions that have been called to get
+ * to the current point in code.
</ins><span class="cx"> *
</span><del>- * @link http://core.trac.wordpress.org/ticket/19589
</del><span class="cx"> * @since 3.4.0
</span><span class="cx"> *
</span><del>- * @param string $ignore_class A class to ignore all function calls within - useful when you want to just give info about the callee
- * @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
- * @return string|array Either a string containing a reversed comma separated trace or an array of individual calls.
</del><ins>+ * @see http://core.trac.wordpress.org/ticket/19589
+ *
+ * @param string $ignore_class Optional. A class to ignore all function calls within - useful
+ * 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.
</ins><span class="cx"> */
</span><span class="cx"> function wp_debug_backtrace_summary( $ignore_class = null, $skip_frames = 0, $pretty = true ) {
</span><span class="cx"> if ( version_compare( PHP_VERSION, '5.2.5', '>=' ) )
</span><span class="lines">@@ -4304,14 +4332,15 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Retrieve ids that are not already present in the cache
</del><ins>+ * Retrieve ids that are not already present in the cache.
</ins><span class="cx"> *
</span><span class="cx"> * @since 3.4.0
</span><ins>+ * @access private
</ins><span class="cx"> *
</span><del>- * @param array $object_ids ID list
- * @param string $cache_key The cache bucket to check against
</del><ins>+ * @param array $object_ids ID list.
+ * @param string $cache_key The cache bucket to check against.
</ins><span class="cx"> *
</span><del>- * @return array
</del><ins>+ * @return array List of ids not present in the cache.
</ins><span class="cx"> */
</span><span class="cx"> function _get_non_cached_ids( $object_ids, $cache_key ) {
</span><span class="cx"> $clean = array();
</span><span class="lines">@@ -4331,7 +4360,7 @@
</span><span class="cx"> * @since 3.4.0
</span><span class="cx"> * @access private
</span><span class="cx"> *
</span><del>- * @return bool true|false
</del><ins>+ * @return bool true|false Whether the device is able to upload files.
</ins><span class="cx"> */
</span><span class="cx"> function _device_can_upload() {
</span><span class="cx"> if ( ! wp_is_mobile() )
</span><span class="lines">@@ -4351,8 +4380,8 @@
</span><span class="cx"> /**
</span><span class="cx"> * Test if a given path is a stream URL
</span><span class="cx"> *
</span><del>- * @param string $path The resource path or URL
- * @return bool True if the path is a stream URL
</del><ins>+ * @param string $path The resource path or URL.
+ * @return bool True if the path is a stream URL.
</ins><span class="cx"> */
</span><span class="cx"> function wp_is_stream( $path ) {
</span><span class="cx"> $wrappers = stream_get_wrappers();
</span><span class="lines">@@ -4372,7 +4401,7 @@
</span><span class="cx"> * @param int $day Day number.
</span><span class="cx"> * @param int $year Year number.
</span><span class="cx"> * @param string $source_date The date to filter.
</span><del>- * @return bool True if valid date, false if not valid date.
</del><ins>+ * @return bool True if valid date, false if not valid date.
</ins><span class="cx"> */
</span><span class="cx"> function wp_checkdate( $month, $day, $year, $source_date ) {
</span><span class="cx"> /**
</span><span class="lines">@@ -4411,6 +4440,9 @@
</span><span class="cx"> /**
</span><span class="cx"> * Filter whether to load the authentication check.
</span><span class="cx"> *
</span><ins>+ * Passing a falsey value to the filter will effectively short-circuit
+ * loading the authentication check.
+ *
</ins><span class="cx"> * @since 3.6.0
</span><span class="cx"> *
</span><span class="cx"> * @param bool $show Whether to load the authentication check.
</span><span class="lines">@@ -4487,17 +4519,20 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Return RegEx body to liberally match an opening HTML tag that:
</del><ins>+ * Return RegEx body to liberally match an opening HTML tag.
+ *
+ * Matches an opening HTML tag that:
</ins><span class="cx"> * 1. Is self-closing or
</span><span class="cx"> * 2. Has no body but has a closing tag of the same name or
</span><span class="cx"> * 3. Contains a body and a closing tag of the same name
</span><span class="cx"> *
</span><del>- * Note: this RegEx does not balance inner tags and does not attempt to produce valid HTML
</del><ins>+ * Note: this RegEx does not balance inner tags and does not attempt
+ * to produce valid HTML
</ins><span class="cx"> *
</span><span class="cx"> * @since 3.6.0
</span><span class="cx"> *
</span><del>- * @param string $tag An HTML tag name. Example: 'video'
- * @return string
</del><ins>+ * @param string $tag An HTML tag name. Example: 'video'.
+ * @return string Tag RegEx.
</ins><span class="cx"> */
</span><span class="cx"> function get_tag_regex( $tag ) {
</span><span class="cx"> if ( empty( $tag ) )
</span><span class="lines">@@ -4506,14 +4541,16 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Return a canonical form of the provided charset appropriate for passing to PHP
</del><ins>+ * Retrieve a canonical form of the provided charset appropriate for passing to PHP
</ins><span class="cx"> * functions such as htmlspecialchars() and charset html attributes.
</span><span class="cx"> *
</span><del>- * @link http://core.trac.wordpress.org/ticket/23688
</del><span class="cx"> * @since 3.6.0
</span><ins>+ * @access private
</ins><span class="cx"> *
</span><del>- * @param string A charset name
- * @return string The canonical form of the charset
</del><ins>+ * @see http://core.trac.wordpress.org/ticket/23688
+ *
+ * @param string $charset A charset name.
+ * @return string The canonical form of the charset.
</ins><span class="cx"> */
</span><span class="cx"> function _canonical_charset( $charset ) {
</span><span class="cx"> if ( 'UTF-8' === $charset || 'utf-8' === $charset || 'utf8' === $charset ||
</span><span class="lines">@@ -4528,22 +4565,27 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Sets the mbstring internal encoding to a binary safe encoding when func_overload is enabled.
</del><ins>+ * Set the mbstring internal encoding to a binary safe encoding when func_overload
+ * is enabled.
</ins><span class="cx"> *
</span><del>- * When mbstring.func_overload is in use for multi-byte encodings, the results from strlen() and
- * similar functions respect the utf8 characters, causing binary data to return incorrect lengths.
</del><ins>+ * When mbstring.func_overload is in use for multi-byte encodings, the results from
+ * strlen() and similar functions respect the utf8 characters, causing binary data
+ * to return incorrect lengths.
</ins><span class="cx"> *
</span><del>- * This function overrides the mbstring encoding to a binary-safe encoding, and resets it to the
- * users expected encoding afterwards through the `reset_mbstring_encoding` function.
</del><ins>+ * This function overrides the mbstring encoding to a binary-safe encoding, and
+ * resets it to the users expected encoding afterwards through the
+ * `reset_mbstring_encoding` function.
</ins><span class="cx"> *
</span><del>- * It is safe to recursively call this function, however each `mbstring_binary_safe_encoding()`
- * call must be followed up with an equal number of `reset_mbstring_encoding()` calls.
</del><ins>+ * It is safe to recursively call this function, however each
+ * `mbstring_binary_safe_encoding()` call must be followed up with an equal number
+ * of `reset_mbstring_encoding()` calls.
</ins><span class="cx"> *
</span><ins>+ * @since 3.7.0
+ *
</ins><span class="cx"> * @see reset_mbstring_encoding()
</span><span class="cx"> *
</span><del>- * @since 3.7.0
- *
- * @param bool $reset Whether to reset the encoding back to a previously-set encoding.
</del><ins>+ * @param bool $reset Optional. Whether to reset the encoding back to a previously-set encoding.
+ * Default false.
</ins><span class="cx"> */
</span><span class="cx"> function mbstring_binary_safe_encoding( $reset = false ) {
</span><span class="cx"> static $encodings = array();
</span><span class="lines">@@ -4568,7 +4610,7 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Resets the mbstring internal encoding to a users previously set encoding.
</del><ins>+ * Reset the mbstring internal encoding to a users previously set encoding.
</ins><span class="cx"> *
</span><span class="cx"> * @see mbstring_binary_safe_encoding()
</span><span class="cx"> *
</span><span class="lines">@@ -4579,12 +4621,12 @@
</span><span class="cx"> }
</span><span class="cx">
</span><span class="cx"> /**
</span><del>- * Alternative to filter_var( $var, FILTER_VALIDATE_BOOLEAN )
</del><ins>+ * Alternative to filter_var( $var, FILTER_VALIDATE_BOOLEAN ).
</ins><span class="cx"> *
</span><span class="cx"> * @since 4.0.0
</span><span class="cx"> *
</span><del>- * @param mixed $var
- * @return boolean
</del><ins>+ * @param mixed $var Boolean value to validate.
+ * @return bool Whether the value is validated.
</ins><span class="cx"> */
</span><span class="cx"> function wp_validate_boolean( $var ) {
</span><span class="cx"> if ( is_bool( $var ) ) {
</span></span></pre>
</div>
</div>
</body>
</html>