Ticket #26185: 26185.diff

wp-includes/functions.php

@@ -69 +69 @@
 
 /**
  * Retrieve the date in localized format, based on timestamp.
- *
  * If the locale specifies the locale month and weekday, then the locale will
  * take over the format for the date. If it isn't, then the date format string
  * will be used instead.
@@ -76 +75 @@
  *
  * @since 0.71
  *
- * @param string $dateformatstring Format to display the date.
- * @param int $unixtimestamp Optional. Unix timestamp.
- * @param bool $gmt Optional, default is false. Whether to convert to GMT for time.
+ * @param string   $dateformatstring Format to display the date.
+ * @param bool|int $unixtimestamp    Optional. Unix timestamp.
+ * @param bool     $gmt              Optional, default is false. Whether to convert to GMT for time.
+ *
  * @return string The date, translated if locale specifies it.
  */
 function date_i18n( $dateformatstring, $unixtimestamp = false, $gmt = false ) {
@@ -159 +159 @@
 /**
  * Convert number of bytes largest unit bytes will fit into.
  *
- * It is easier to read 1kB than 1024 bytes and 1MB than 1048576 bytes. Converts
+ * It is easier to read 1KB than 1024 bytes and 1MB than 1048576 bytes. Converts
  * number of bytes to human readable number by taking the number of that unit
  * that the bytes will go into it. Supports TB value.
  *
@@ -198 +198 @@
  *
  * @since 0.71
  *
- * @param string $mysqlstring Date or datetime field type from mysql.
- * @param int $start_of_week Optional. Start of the week as an integer.
+ * @param string     $mysqlstring   Date or datetime field type from mysql.
+ * @param int|string $start_of_week Optional. Start of the week as an integer.
+ *
  * @return array Keys are 'start' and 'end'.
  */
 function get_weekstartend( $mysqlstring, $start_of_week = '' ) {
@@ -355 +356 @@
  *
  * @global string $post_default_title Default XMLRPC post title.
  *
- * @param string $content XMLRPC XML Request content
- * @return string Post title
+ * @param string $content XMLRPC XML Request content.
+ * @return string Post title.
  */
 function xmlrpc_getposttitle( $content ) {
         global $post_default_title;
@@ -381 +382 @@
  *
  * @global string $post_default_category Default XMLRPC post category.
  *
- * @param string $content XMLRPC XML Request content
+ * @param string $content XMLRPC XML Request content.
  * @return string|array List of categories or category name.
  */
 function xmlrpc_getpostcategory( $content ) {
@@ -402 +403 @@
  * @subpackage XMLRPC
  * @since 0.71
  *
- * @param string $content XMLRPC XML Request content
+ * @param string $content XMLRPC XML Request content.
  * @return string XMLRPC XML Request content without title and category elements.
  */
 function xmlrpc_removepostdata( $content ) {
@@ -413 +414 @@
 }
 
 /**
- * Use RegEx to extract URLs from arbitrary content
+ * Use RegEx to extract URLs from arbitrary content.
  *
  * @since 3.7.0
  *
  * @param string $content
- * @return array URLs found in passed string
+ * @return array URLs found in passed string.
  */
 function wp_extract_urls( $content ) {
         preg_match_all(
@@ -444 +445 @@
  *
  * @uses $wpdb
  *
- * @param string $content Post Content
- * @param int $post_ID Post ID
+ * @param string $content Post Content.
+ * @param int $post_ID Post ID.
  */
 function do_enclose( $content, $post_ID ) {
         global $wpdb;
@@ -591 +592 @@
  *
  * @since 0.71
  * @uses $day Today
- * @uses $previousday Previous day
+ * @uses $previousday Previous day.
  *
  * @return int 1 when new day, 0 if not a new day.
  */
@@ -616 +617 @@
  * @since 2.3.0
  *
  * @param array $data URL-encode key/value pairs.
- * @return string URL encoded string
+ * @return string URL-encoded string.
  */
 function build_query( $data ) {
         return _http_build_query( $data, null, '&', '', false );
 }
 
-// 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
+ * @link 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 string  $prefix Optional. Numeric index. If set, start parameter numbering with it.
+ * @param string  $sep Optional. Argument separator; defaults to 'arg_separator.output'.
+ * @param string        $key Optional. Used to prefix key name.
+ * @param bool          $urlencode Optional. Whether to use {@link urlencode()} in the result.
+ *
+ * @return string The query string.
+ */
 function _http_build_query($data, $prefix=null, $sep=null, $key='', $urlencode=true) {
         $ret = array();
 
@@ -801 +815 @@
  *
  * @since 2.0.0
  *
+ * @global $wp
+ * @global $wp_query
+ * @global $wp_the_query
+ *
  * @param string $query_vars Default WP_Query arguments.
  */
 function wp( $query_vars = '' ) {
@@ -816 +834 @@
  *
  * @since 2.3.0
  *
+ * @global $wp_header_to_desc
+ *
  * @param int $code HTTP status code.
  * @return string Empty string if not found, or description if found.
  */
@@ -918 +938 @@
  * Gets the header information to prevent caching.
  *
  * The several different headers cover the different ways cache prevention is handled
- * by different browsers
+ * by different browsers.
  *
  * @since 2.8.0
  *
@@ -987 +1007 @@
  *
  * @since 2.0.0
  *
- * @return int Number of database queries
+ * @global $wpdb
+ *
+ * @return int Number of database queries.
  */
 function get_num_queries() {
         global $wpdb;
@@ -999 +1021 @@
  *
  * @since 1.0.0
  *
- * @param string $yn Character string containing either 'y' or 'n'
- * @return bool True if yes, false on anything else
+ * @param string $yn Character string containing either 'y' or 'n'.
+ * @return bool True if yes, false on anything else.
  */
 function bool_from_yn( $yn ) {
         return ( strtolower( $yn ) == 'y' );
@@ -1015 +1037 @@
  * It is better to only have one hook for each feed.
  *
  * @since 2.1.0
- * @uses $wp_query Used to tell if the use a comment feed.
+ *
+ * @global $wp_query Used to tell if the use a comment feed.
  * @uses do_action() Calls 'do_feed_$feed' hook, if a hook exists for the feed.
  */
 function do_feed() {
@@ -1135 +1158 @@
  * Checks for the option siteurl for whether WordPress is installed.
  *
  * @since 2.1.0
- * @uses $wpdb
  *
+ * @global $wpdb
+ *
  * @return bool Whether blog is already installed.
  */
 function is_blog_installed() {
@@ -1289 +1313 @@
  * @subpackage Security
  * @since 2.0.4
  *
- * @param bool $echo Whether to echo the original http referer
+ * @param bool $echo Whether to echo the original http referer.
  * @param string $jump_back_to Optional, default is 'current'. Can be 'previous' or page you want to jump back to.
  * @return string Original referer field.
  */
@@ -1402 +1426 @@
  *
  * @since 2.5.0
  *
- * @param string $path File path
+ * @param string $path File path to check.
  * @return bool True if path is absolute, false is not absolute.
  */
 function path_is_absolute( $path ) {
@@ -1443 +1467 @@
  * Determines a writable directory for temporary files.
  * Function's preference is the return value of <code>sys_get_temp_dir()</code>,
  * followed by your PHP temporary upload directory, followed by WP_CONTENT_DIR,
- * before finally defaulting to /tmp/
+ * before finally defaulting to /tmp/.
  *
  * In the event that this function does not find a writable location,
  * It may be overridden by the <code>WP_TEMP_DIR</code> constant in
@@ -1451 +1475 @@
  *
  * @since 2.5.0
  *
- * @return string Writable temporary directory
+ * @return string Writable temporary directory.
  */
 function get_temp_dir() {
         static $temp;
@@ -1489 +1513 @@
  *
  * @since 3.6.0
  *
- * @param string $path
- * @return bool
+ * @param string $path Path to directory to check.
+ * @return bool True if writable, false if not writable.
  */
 function wp_is_writable( $path ) {
         if ( 'WIN' === strtoupper( substr( PHP_OS, 0, 3 ) ) )
@@ -1500 +1524 @@
 }
 
 /**
- * Workaround for Windows bug in is_writable() function
+ * Workaround for Windows bug in is_writable() function.
  *
  * PHP has issues with Windows ACL's for determine if a
  * directory is writable or not, this works around them by
@@ -1512 +1536 @@
  *
  * @since 2.8.0
  *
- * @param string $path
- * @return bool
+ * @param string $path Path to directory to check.
+ * @return bool True if writable, false if not writable.
  */
 function win_is_writable( $path ) {
 
@@ -1751 +1775 @@
  *
  * @since 2.0.0
  *
- * @param string $name
+ * @param string $name Name of the file to create.
  * @param null $deprecated Never used. Set to null.
- * @param mixed $bits File content
+ * @param mixed $bits File content.
  * @param string $time Optional. Time formatted in 'yyyy/mm'.
- * @return array
+ * @return array On success: file path and url; on error: error details.
  */
 function wp_upload_bits( $name, $deprecated, $bits, $time = null ) {
         if ( !empty( $deprecated ) )
@@ -1885 +1909 @@
  * @since 3.0.0
  *
  * @param string $file Full path to the file.
- * @param string $filename The name of the file (may differ from $file due to $file being in a tmp directory)
+ * @param string $filename The name of the file (may differ from $file due to $file being in a tmp directory).
  * @param array $mimes Optional. Key is the file extension with value as the mime type.
- * @return array Values for the extension, MIME, and either a corrected filename or false if original $filename is valid
+ * @return array Values for the extension, MIME, and either a corrected filename or false if original $filename is valid.
  */
 function wp_check_filetype_and_ext( $file, $filename, $mimes = null ) {
 
@@ -1946 +1970 @@
  *
  * @since 3.5.0
  *
- * @uses apply_filters() Calls 'mime_types' on returned array. This filter should
- * be used to add types, not remove them. To remove types use the upload_mimes filter.
+ * @uses apply_filters() Calls 'mime_types' on returned array.
+ *                                                                                       This filter should be used to add types, not remove them.
+ *                                                                                       To remove types use the upload_mimes filter.
  *
  * @return array Array of mime types keyed by the file extension regex corresponding to those types.
  */
@@ -2052 +2077 @@
  *
  * @since 2.8.6
  *
- * @uses apply_filters() Calls 'upload_mimes' on returned array
- * @uses wp_get_upload_mime_types() to fetch the list of mime types
+ * @uses apply_filters() Calls 'upload_mimes' on returned array.
+ * @uses wp_get_upload_mime_types() to fetch the list of mime types.
  *
  * @param int|WP_User $user Optional. User to check. Defaults to current user.
  * @return array Array of mime types keyed by the file extension regex corresponding to those types.
@@ -2127 +2152 @@
  * Kill WordPress execution and display HTML message with error message.
  *
  * This is the default handler for wp_die if you want a custom one for your
- * site then you can overload using the wp_die_handler filter in wp_die
+ * site then you can overload using the wp_die_handler filter in wp_die.
  *
  * @since 3.0.0
  * @access private
@@ -2310 +2335 @@
  * @since 3.2.0
  * @access private
  *
+ * @global $wp_xmlrpc_server
+ *
  * @param string $message Error message.
  * @param string $title Error title.
  * @param string|array $args Optional arguments to control behavior.
@@ -2418 +2445 @@
  * @package WordPress
  * @since 2.2.0
  *
- * @param string $url URL for the home location
+ * @param string $url URL for the home location.
  * @return string Homepage location.
  */
 function _config_wp_home( $url = '' ) {
@@ -2439 +2466 @@
  * @since 2.2.0
  *
  * @param string $url URL to set the WordPress site location.
- * @return string The WordPress Site URL
+ * @return string The WordPress Site URL.
  */
 function _config_wp_siteurl( $url = '' ) {
         if ( defined( 'WP_SITEURL' ) )
@@ -2590 +2617 @@
 
 /**
  * Merge user defined arguments into defaults array.
- *
  * This function is used throughout WordPress to allow for both string or array
  * to be merged into another array.
  *
  * @since 2.2.0
  *
- * @param string|array $args Value to merge with $defaults
- * @param array $defaults Array that serves as the defaults.
+ * @param string|array $args     Value to merge with $defaults.
+ * @param array|string $defaults Optional. Array that serves as the defaults.
+ *
  * @return array Merged user defined values with defaults.
  */
 function wp_parse_args( $args, $defaults = '' ) {
@@ -2618 +2645 @@
  *
  * @since 3.0.0
  *
- * @param array|string $list
- * @return array Sanitized array of IDs
+ * @param array|string $list List of IDs.
+ * @return array Sanitized array of IDs.
  */
 function wp_parse_id_list( $list ) {
         if ( !is_array($list) )
@@ -2633 +2660 @@
  *
  * @since 3.1.0
  *
- * @param array $array The original array
- * @param array $keys The list of keys
- * @return array The array slice
+ * @param array $array The original array.
+ * @param array $keys The list of keys.
+ * @return array The array slice.
  */
 function wp_array_slice_assoc( $array, $keys ) {
         $slice = array();
@@ -2651 +2678 @@
  *
  * @since 3.0.0
  *
- * @param array $list An array of objects to filter
- * @param array $args An array of key => value arguments to match against each object
+ * @param array $list An array of objects to filter.
+ * @param array $args An array of key => value arguments to match against each object.
  * @param string $operator The logical operation to perform. 'or' means only one element
- *      from the array needs to match; 'and' means all elements must match. The default is 'and'.
- * @param bool|string $field A field from the object to place instead of the entire object
- * @return array A list of objects or object fields
+ *                                                                                               from the array needs to match; 'and' means all elements must match.
+ *                                                                                               The default is 'and'.
+ * @param bool|string $field A field from the object to place instead of the entire object.
+ * @return array A list of objects or object fields.
  */
 function wp_filter_object_list( $list, $args = array(), $operator = 'and', $field = false ) {
         if ( ! is_array( $list ) )
@@ -2675 +2703 @@
  *
  * @since 3.1.0
  *
- * @param array $list An array of objects to filter
- * @param array $args An array of key => value arguments to match against each object
+ * @param array $list An array of objects to filter.
+ * @param array $args An array of key => value arguments to match against each object.
  * @param string $operator The logical operation to perform:
  *    'AND' means all elements from the array must match;
  *    'OR' means only one element needs to match;
  *    'NOT' means no elements may match.
  *   The default is 'AND'.
- * @return array
+ * @return array The filtered object list.
  */
 function wp_list_filter( $list, $args = array(), $operator = 'AND' ) {
         if ( ! is_array( $list ) )
@@ -2719 +2747 @@
  *
  * @since 3.1.0
  *
- * @param array $list A list of objects or arrays
- * @param int|string $field A field from the object to place instead of the entire object
- * @return array
+ * @param array $list A list of objects or arrays.
+ * @param int|string $field A field from the object to place instead of the entire object.
+ * @return array The filtered $list.
  */
 function wp_list_pluck( $list, $field ) {
         foreach ( $list as $key => $value ) {
@@ -2794 +2822 @@
  * in WordPress 2.5.0.
  *
  * @since 2.3.2
- * @uses $wpdb
+ * @global $wpdb
  */
 function dead_db() {
         global $wpdb;
@@ -2832 +2860 @@
 }
 
 /**
- * Converts value to nonnegative integer.
+ * Converts value to non-negative integer.
  *
  * @since 2.5.0
  *
- * @param mixed $maybeint Data you wish to have converted to a nonnegative integer
- * @return int An nonnegative integer
+ * @param mixed $maybeint Data you wish to have converted to a non-negative integer.
+ * @return int An non-negative integer.
  */
 function absint( $maybeint ) {
         return abs( intval( $maybeint ) );
@@ -2851 +2879 @@
  *
  * @since 2.5.0
  *
- * @param string $url
- * @return bool Whether SSL access is available
+ * @param string $url The URL of the blog to check.
+ * @return bool Whether SSL access is available.
  */
 function url_is_accessable_via_ssl($url)
 {
@@ -2899 +2927 @@
  * @uses apply_filters() Calls 'deprecated_function_trigger_error' and expects boolean value of true to do
  *   trigger or false to not trigger error.
  *
- * @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
+ * @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.
  */
 function _deprecated_function( $function, $version, $replacement = null ) {
 
@@ -2944 +2972 @@
  * @uses apply_filters() Calls 'deprecated_file_trigger_error' and expects boolean value of true to do
  *   trigger or false to not trigger error.
  *
- * @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
+ * @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.
  */
 function _deprecated_file( $file, $version, $replacement = null, $message = '' ) {
 
@@ -2977 +3005 @@
  * used by comparing it to its default value or evaluating whether it is empty.
  * For example:
  * <code>
- * if ( !empty($deprecated) )
+ * if ( ! empty( $deprecated ) )
  *      _deprecated_argument( __FUNCTION__, '3.0' );
  * </code>
  *
@@ -2997 +3025 @@
  * @uses apply_filters() Calls 'deprecated_argument_trigger_error' and expects boolean value of true to do
  *   trigger or false to not trigger error.
  *
- * @param string $function The function that was called
- * @param string $version The version of WordPress that deprecated the argument used
+ * @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.
  */
 function _deprecated_argument( $function, $version, $message = null ) {
@@ -3079 +3107 @@
  *
  * @since 2.5.0
  *
- * @param string $mod e.g. mod_rewrite
- * @param bool $default The default return value if the module is not found
- * @return bool
+ * @param string $mod Module to check, e.g. mod_rewrite.
+ * @param bool $default The default return value if the module is not found.
+ * @return bool True if module loaded, false if not loaded.
  */
 function apache_mod_loaded($mod, $default = false) {
         global $is_apache;
@@ -3108 +3136 @@
  *
  * @since 2.8.0
  *
- * @return bool
+ * @return bool True if permalinks are supported, false if not supported.
  */
 function iis7_supports_permalinks() {
         global $is_iis7;
@@ -3132 +3160 @@
 
 /**
  * File validates against allowed set of defined rules.
- *
  * A return value of '1' means that the $file contains either '..' or './'. A
  * return value of '2' means that the $file contains ':' after the first
  * character. A return value of '3' means that the file is not in the allowed
@@ -3140 +3167 @@
  *
  * @since 1.2.0
  *
- * @param string $file File path.
- * @param array $allowed_files List of allowed files.
+ * @param string       $file          File path.
+ * @param array|string $allowed_files Optional. List of allowed files.
+ *
  * @return int 0 means nothing is wrong, greater than 0 means something was wrong.
  */
 function validate_file( $file, $allowed_files = '' ) {
@@ -3227 +3255 @@
  *
  * @since 2.6.0
  *
- * @return string
+ * @return string The best-guess URL of the site.
  */
 function wp_guess_url() {
         if ( defined('WP_SITEURL') && '' != WP_SITEURL ) {
@@ -3281 +3309 @@
  * @since 3.3.0
  *
  * @param bool $suspend Optional. Suspends additions if true, re-enables them if false.
- * @return bool The current suspend setting
+ * @return bool The current suspend setting.
  */
 function wp_suspend_cache_addition( $suspend = null ) {
         static $_suspend = false;
@@ -3301 +3329 @@
  *
  * @since 2.7.0
  *
- * @param bool $suspend Whether to suspend or enable cache invalidation
- * @return bool The current suspend setting
+ * @param bool $suspend Whether to suspend or enable cache invalidation.
+ * @return bool The current suspend setting.
  */
 function wp_suspend_cache_invalidation($suspend = true) {
         global $_wp_suspend_cache_invalidation;
@@ -3338 +3366 @@
  *
  * @since 3.7.0
  *
+ * @global $wpdb
+ *
  * @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.
  */
@@ -3377 +3407 @@
  * @since 3.0.0
  * @package WordPress
  *
- * @return bool True if multisite and global terms enabled
+ * @return bool True if multisite and global terms enabled.
  */
 function global_terms_enabled() {
         if ( ! is_multisite() )
@@ -3401 +3431 @@
  *
  * @since 2.8.0
  *
- * @return float|bool
+ * @return float|bool Timezone offset; false if not set or if any errors.
  */
 function wp_timezone_override_offset() {
         if ( !$timezone_string = get_option( 'timezone_string' ) ) {
@@ -3423 +3453 @@
  *
  * @param array $a
  * @param array $b
- * @return int
+ * @return int Less than 0 if $ is greater, 0 if equal, greater than 0 if $b is greater.
  */
 function _wp_timezone_choice_usort_callback( $a, $b ) {
         // Don't use translated versions of Etc
@@ -3468 +3498 @@
  *
  * @since 2.9.0
  *
- * @param string $selected_zone Selected Zone
- * @return string
+ * @param string $selected_zone Selected Zone.
+ * @return string Formatted timezones.
  */
 function wp_timezone_choice( $selected_zone ) {
         static $mo_loaded = false;
@@ -3594 +3624 @@
 
 /**
  * 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
+ * @link http://core.trac.wordpress.org/ticket/8497
  *
- * @param string $str
- * @return string
+ * @param string $str String to clean.
+ * @return string The cleaned-up string.
  */
 function _cleanup_header_comment($str) {
         return trim(preg_replace("/\s*(?:\*\/|\?>).*/", '', $str));
@@ -3609 +3639 @@
  * Permanently deletes posts, pages, attachments, and comments which have been in the trash for EMPTY_TRASH_DAYS.
  *
  * @since 2.9.0
+ *
+ * @global $wpdb
  */
 function wp_scheduled_delete() {
         global $wpdb;
@@ -3653 +3685 @@
 /**
  * Retrieve metadata from a file.
  *
- * Searches for metadata in the first 8kiB of a file, such as a plugin or theme.
+ * Searches for metadata in the first 8KiB of a file, such as a plugin or theme.
  * Each piece of metadata must be on its own line. Fields can not span multiple
  * lines, the value will get cut at the end of the first line.
  *
- * If the file data is not within that first 8kiB, then the author should correct
+ * If the file data is not within that first 8KiB, then the author should correct
  * their plugin file and move the data headers to the top.
  *
- * @see http://codex.wordpress.org/File_Header
+ * @link http://codex.wordpress.org/File_Header
  *
  * @since 2.9.0
- * @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"
+ *
+ * @param string $file Path to the file.
+ * @param array $default_headers {
+ *              An array of header values in themes and plugins.
+ *
+ *              @type string $key HeaderKey. Accepts string 'Header Name'.
+ * }
+ * @param string $context If specified adds filter hook "extra_{$context}_headers".
+ * @return array
  */
 function get_file_data( $file, $default_headers, $context = '' ) {
         // We don't need to write to the file, so just open for reading.
         $fp = fopen( $file, 'r' );
 
-        // Pull only the first 8kiB of the file in.
+        // Pull only the first 8KiB of the file in.
         $file_data = fread( $fp, 8192 );
 
         // PHP will close file handle, but we are good citizens.
@@ -3704 +3742 @@
  *
  * @since 3.0.0
  * @see __return_false()
+ *
  * @return bool true
  */
 function __return_true() {
@@ -3717 +3756 @@
  *
  * @since 3.0.0
  * @see __return_true()
+ *
  * @return bool false
  */
 function __return_false() {
@@ -3729 +3769 @@
  * Useful for returning 0 to filters easily.
  *
  * @since 3.0.0
+ *
  * @return int 0
  */
 function __return_zero() {
@@ -3741 +3782 @@
  * Useful for returning an empty array to filters easily.
  *
  * @since 3.0.0
- * @return array Empty array
+ *
+ * @return array Empty array.
  */
 function __return_empty_array() {
         return array();
@@ -3753 +3795 @@
  * Useful for returning null to filters easily.
  *
  * @since 3.4.0
+ *
  * @return null
  */
 function __return_null() {
@@ -3766 +3809 @@
  *
  * @since 3.7.0
  * @see __return_null()
+ *
  * @return string Empty string
  */
 function __return_empty_string() {
@@ -3779 +3823 @@
  * @link http://src.chromium.org/viewvc/chrome?view=rev&revision=6985
  *
  * @since 3.0.0
- * @return none
  */
 function send_nosniff_header() {
         @header( 'X-Content-Type-Options: nosniff' );
@@ -3790 +3833 @@
  *
  * @internal
  * @since 3.0.0
+ *
  * @param string $column
  * @return string
  */
@@ -3812 +3856 @@
 /**
  * Finds hierarchy loops using a callback function that maps object IDs to parent IDs.
  *
+ * @access private
  * @since 3.1.0
- * @access private
  *
- * @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
+ * @param callback $callback function that accepts ( ID, $callback_args ) and outputs parent_ID.
+ * @param int $start The ID to start the loop check.
+ * @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.
  */
 function wp_find_hierarchy_loop( $callback, $start, $start_parent, $callback_args = array() ) {
         $override = is_null( $start_parent ) ? array() : array( $start => $start_parent );
@@ -3836 +3881 @@
  * 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.
  *
+ * @access private
  * @since 3.1.0
- * @access private
  *
- * @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 callback $callback Function that accepts ( ID, callback_arg, ... ) and outputs parent_ID.
+ * @param int $start The ID to start the loop check.
+ * @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
+ *             (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.
  */
 function wp_find_hierarchy_loop_tortoise_hare( $callback, $start, $override = array(), $callback_args = array(), $_return_loop = false ) {
         $tortoise = $hare = $evanescent_hare = $start;
@@ -3881 +3926 @@
  * @link https://developer.mozilla.org/en/the_x-frame-options_response_header
  *
  * @since 3.1.3
- * @return none
  */
 function send_frame_options_header() {
         @header( 'X-Frame-Options: SAMEORIGIN' );
@@ -3913 +3957 @@
  * @link http://core.trac.wordpress.org/ticket/19589
  * @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
- * @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 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.
  */
 function wp_debug_backtrace_summary( $ignore_class = null, $skip_frames = 0, $pretty = true ) {
@@ -3953 +3998 @@
 }
 
 /**
- * Retrieve ids that are not already present in the cache
+ * Retrieve IDs that are not already present in the cache.
  *
  * @since 3.4.0
  *
- * @param array $object_ids ID list
- * @param string $cache_key The cache bucket to check against
+ * @param array $object_ids ID list.
+ * @param string $cache_key The cache bucket to check against.
  *
- * @return array
+ * @return array Cleaned up array of IDs.
  */
 function _get_non_cached_ids( $object_ids, $cache_key ) {
         $clean = array();
@@ -3977 +4022 @@
 /**
  * Test if the current device has the capability to upload files.
  *
+ * @access private
  * @since 3.4.0
- * @access private
  *
- * @return bool true|false
+ * @return bool True if the device allows uploads; false if not.
  */
 function _device_can_upload() {
         if ( ! wp_is_mobile() )
@@ -3998 +4043 @@
 }
 
 /**
- * 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
- * @return bool True if the path is a stream URL
+ * @param string $path The resource path or URL.
+ * @return bool True if the path is a stream URL.
  */
 function wp_is_stream( $path ) {
         $wrappers = stream_get_wrappers();
@@ -4011 +4056 @@
 }
 
 /**
- * Test if the supplied date is valid for the Gregorian calendar
+ * Test if the supplied date is valid for the Gregorian calendar.
  *
  * @since 3.5.0
+ * @see checkdate()
  *
- * @return bool true|false
+ * @param int $month
+ * @param int $day
+ * @param int $year
+ * @param $source_date
+ *
+ * @return bool True if valid date, false if not valid date.
  */
 function wp_checkdate( $month, $day, $year, $source_date ) {
         return apply_filters( 'wp_checkdate', checkdate( $month, $day, $year ), $source_date );
@@ -4024 +4075 @@
 /**
  * Load the auth check for monitoring whether the user is still logged in.
  *
- * Can be disabled with remove_action( 'admin_enqueue_scripts', 'wp_auth_check_load' );
+ * Can be disabled with `remove_action( 'admin_enqueue_scripts', 'wp_auth_check_load' );`.
  *
  * This is disabled for certain screens where a login screen could cause an
  * inconvenient interruption. A filter called wp_auth_check_load can be used
@@ -4095 +4146 @@
 
 /**
  * Check whether a user is still logged in, for the heartbeat.
- *
  * Send a result that shows a log-in box if the user is no longer logged in,
  * or if their cookie is within the grace period.
  *
  * @since 3.6.0
+ *
+ * @param array $response
+ * @param       $data
+ *
+ * @return array
  */
 function wp_auth_check( $response, $data ) {
         $response['wp-auth-check'] = is_user_logged_in() && empty( $GLOBALS['login_grace_period'] );
@@ -4112 +4167 @@
  * 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
  *
- * 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
  *
- * @param string $tag An HTML tag name. Example: 'video'
+ * @param string $tag An HTML tag name. Example: 'video'.
  * @return string
  */
 function get_tag_regex( $tag ) {
@@ -4132 +4187 @@
  * @link http://core.trac.wordpress.org/ticket/23688
  * @since 3.6.0
  *
- * @param string A charset name
- * @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 ) {
         if ( 'UTF-8' === $charset || 'utf-8' === $charset || 'utf8' === $charset ||