Changeset 47122 for trunk/src/wp-includes/functions.php

Timestamp:

01/29/2020 12:43:23 AM (6 years ago)

Author:

SergeyBiryukov

Message:

Docs: Improve inline comments per the documentation standards.

Includes minor code layout fixes for better readability.

See #48303.

File:

• trunk/src/wp-includes/functions.php (modified) (52 diffs)

trunk/src/wp-includes/functions.php

@@ -324 +324 @@
     global $wp_locale;
 
-    // i18n functions are not available in SHORTINIT mode
+    // i18n functions are not available in SHORTINIT mode.
     if ( ! function_exists( '_x' ) ) {
         return $date;
@@ -385 +385 @@
     }
 
-    // Used for locale-specific rules
+    // Used for locale-specific rules.
     $locale = get_locale();
 
@@ -591 +591 @@
  */
 function maybe_unserialize( $original ) {
-    if ( is_serialized( $original ) ) { // don't attempt to unserialize data that wasn't serialized going in
+    if ( is_serialized( $original ) ) { // Don't attempt to unserialize data that wasn't serialized going in.
         return @unserialize( $original );
     }
@@ -610 +610 @@
  */
 function is_serialized( $data, $strict = true ) {
-    // if it isn't a string, it isn't serialized.
+    // If it isn't a string, it isn't serialized.
     if ( ! is_string( $data ) ) {
         return false;
@@ -654 +654 @@
                 return false;
             }
-            // or else fall through
+            // Or else fall through.
         case 'a':
         case 'O':
@@ -709 +709 @@
     }
 
-    // Double serialization is required for backward compatibility.
-    // See https://core.trac.wordpress.org/ticket/12930
-    // Also the world will end. See WP 3.6.1.
+    /*
+     * Double serialization is required for backward compatibility.
+     * See https://core.trac.wordpress.org/ticket/12930
+     * Also the world will end. See WP 3.6.1.
+     */
     if ( is_serialized( $data, false ) ) {
         return serialize( $data );
@@ -898 +900 @@
                 $allowed_types = array( 'video', 'audio' );
 
-                // Check to see if we can figure out the mime type from
-                // the extension
+                // Check to see if we can figure out the mime type from the extension.
                 $url_parts = @parse_url( $url );
                 if ( false !== $url_parts ) {
@@ -1122 +1123 @@
 
     wp_parse_str( $query, $qs );
-    $qs = urlencode_deep( $qs ); // this re-URL-encodes things that were already in the query string
+    $qs = urlencode_deep( $qs ); // This re-URL-encodes things that were already in the query string.
     if ( is_array( $args[0] ) ) {
         foreach ( $args[0] as $k => $v ) {
@@ -1155 +1156 @@
  */
 function remove_query_arg( $key, $query = false ) {
-    if ( is_array( $key ) ) { // removing multiple keys
+    if ( is_array( $key ) ) { // Removing multiple keys.
         foreach ( $key as $k ) {
             $query = add_query_arg( $k, false, $query );
@@ -1486 +1487 @@
 
     header( 'Content-Type: text/javascript; charset=' . get_bloginfo( 'charset' ) );
-    header( 'Vary: Accept-Encoding' ); // Handle proxies
+    header( 'Vary: Accept-Encoding' ); // Handle proxies.
     header( 'Expires: ' . gmdate( 'D, d M Y H:i:s', time() + $expiresOffset ) . ' GMT' );
 }
@@ -1704 +1705 @@
         $alloptions = wp_load_alloptions();
     }
-    // If siteurl is not set to autoload, check it specifically
+    // If siteurl is not set to autoload, check it specifically.
     if ( ! isset( $alloptions['siteurl'] ) ) {
         $installed = $wpdb->get_var( "SELECT option_value FROM $wpdb->options WHERE option_name = 'siteurl'" );
@@ -2079 +2080 @@
 function wp_normalize_path( $path ) {
     $wrapper = '';
+
     if ( wp_is_stream( $path ) ) {
         list( $wrapper, $path ) = explode( '://', $path, 2 );
-        $wrapper               .= '://';
-    }
-
-    // Standardise all paths to use /
+
+        $wrapper .= '://';
+    }
+
+    // Standardise all paths to use '/'.
     $path = str_replace( '\\', '/', $path );
 
@@ -2090 +2093 @@
     $path = preg_replace( '|(?<=.)/+|', '/', $path );
 
-    // Windows paths should uppercase the drive letter
+    // Windows paths should uppercase the drive letter.
     if ( ':' === substr( $path, 1, 1 ) ) {
         $path = ucfirst( $path );
@@ -2182 +2185 @@
  */
 function win_is_writable( $path ) {
-
-    if ( $path[ strlen( $path ) - 1 ] == '/' ) { // if it looks like a directory, check a random file within the directory
+    if ( $path[ strlen( $path ) - 1 ] == '/' ) {
+        // If it looks like a directory, check a random file within the directory.
         return win_is_writable( $path . uniqid( mt_rand() ) . '.tmp' );
-    } elseif ( is_dir( $path ) ) { // If it's a directory (and not a file) check a random file within the directory
+    } elseif ( is_dir( $path ) ) {
+        // If it's a directory (and not a file), check a random file within the directory.
         return win_is_writable( $path . '/' . uniqid( mt_rand() ) . '.tmp' );
     }
-    // check tmp file for read/write capabilities
+
+    // Check tmp file for read/write capabilities.
     $should_delete_tmp_file = ! file_exists( $path );
-    $f                      = @fopen( $path, 'a' );
+
+    $f = @fopen( $path, 'a' );
     if ( $f === false ) {
         return false;
     }
     fclose( $f );
+
     if ( $should_delete_tmp_file ) {
         unlink( $path );
     }
+
     return true;
 }
@@ -2328 +2336 @@
         $dir = WP_CONTENT_DIR . '/uploads';
     } elseif ( 0 !== strpos( $upload_path, ABSPATH ) ) {
-        // $dir is absolute, $upload_path is (maybe) relative to ABSPATH
+        // $dir is absolute, $upload_path is (maybe) relative to ABSPATH.
         $dir = path_join( ABSPATH, $upload_path );
     } else {
@@ -2352 +2360 @@
     }
 
-    // If multisite (and if not the main site in a post-MU network)
+    // If multisite (and if not the main site in a post-MU network).
     if ( is_multisite() && ! ( is_main_network() && is_main_site() && defined( 'MULTISITE' ) ) ) {
 
@@ -2403 +2411 @@
     $subdir = '';
     if ( get_option( 'uploads_use_yearmonth_folders' ) ) {
-        // Generate the yearly and monthly dirs
+        // Generate the yearly and monthly directories.
         if ( ! $time ) {
             $time = current_time( 'mysql' );
@@ -2525 +2533 @@
 
                 // Ensure this never goes into infinite loop
-                // as it uses pathinfo() and regex in the check but string replacement for the changes.
+                // as it uses pathinfo() and regex in the check, but string replacement for the changes.
                 $count = count( $files );
                 $i     = 0;
@@ -2566 +2574 @@
     $ext   = pathinfo( $filename, PATHINFO_EXTENSION );
 
-    // Edge case, file names like `.ext`
+    // Edge case, file names like `.ext`.
     if ( empty( $fname ) ) {
         return false;
@@ -2682 +2690 @@
     clearstatcache();
 
-    // Set correct file permissions
+    // Set correct file permissions.
     $stat  = @ stat( dirname( $new_file ) );
     $perms = $stat['mode'] & 0007777;
@@ -2689 +2697 @@
     clearstatcache();
 
-    // Compute the URL
+    // Compute the URL.
     $url = $upload['url'] . "/$filename";
 
@@ -2786 +2794 @@
     $proper_filename = false;
 
-    // Do basic extension validation and MIME mapping
+    // Do basic extension validation and MIME mapping.
     $wp_filetype = wp_check_filetype( $filename, $mimes );
     $ext         = $wp_filetype['ext'];
     $type        = $wp_filetype['type'];
 
-    // We can't do any further validation without a file to work with
+    // We can't do any further validation without a file to work with.
     if ( ! file_exists( $file ) ) {
         return compact( 'ext', 'type', 'proper_filename' );
@@ -2801 +2809 @@
     if ( $type && 0 === strpos( $type, 'image/' ) ) {
 
-        // Attempt to figure out what type of image it actually is
+        // Attempt to figure out what type of image it actually is.
         $real_mime = wp_get_image_mime( $file );
 
@@ -2823 +2831 @@
             );
 
-            // Replace whatever is after the last period in the filename with the correct extension
+            // Replace whatever is after the last period in the filename with the correct extension.
             if ( ! empty( $mime_to_ext[ $real_mime ] ) ) {
                 $filename_parts = explode( '.', $filename );
@@ -2831 +2839 @@
 
                 if ( $new_filename != $filename ) {
-                    $proper_filename = $new_filename; // Mark that it changed
+                    $proper_filename = $new_filename; // Mark that it changed.
                 }
-                // Redefine the extension / MIME
+                // Redefine the extension / MIME.
                 $wp_filetype = wp_check_filetype( $new_filename, $mimes );
                 $ext         = $wp_filetype['ext'];
@@ -2850 +2858 @@
         finfo_close( $finfo );
 
-        // fileinfo often misidentifies obscure files as one of these types
+        // fileinfo often misidentifies obscure files as one of these types.
         $nonspecific_types = array(
             'application/octet-stream',
@@ -2921 +2929 @@
     }
 
-    // The mime type must be allowed
+    // The mime type must be allowed.
     if ( $type ) {
         $allowed = get_allowed_mime_types();
@@ -3032 +3040 @@
             'webm'                         => 'video/webm',
             'mkv'                          => 'video/x-matroska',
-            '3gp|3gpp'                     => 'video/3gpp', // Can also be audio
-            '3g2|3gp2'                     => 'video/3gpp2', // Can also be audio
+            '3gp|3gpp'                     => 'video/3gpp',  // Can also be audio.
+            '3g2|3gp2'                     => 'video/3gpp2', // Can also be audio.
             // Text formats.
             'txt|asc|c|cc|h|srt'           => 'text/plain',
@@ -3983 +3991 @@
  *
  * @ignore
- * @since      4.4.0
+ * @since 4.4.0
  * @deprecated 5.3.0 This function is no longer needed as support for PHP 5.2-5.3
  *                   has been dropped.
@@ -4223 +4231 @@
     global $wpsmiliestrans, $wp_smiliessearch;
 
-    // don't bother setting up smilies if they are disabled
+    // Don't bother setting up smilies if they are disabled.
     if ( ! get_option( 'use_smilies' ) ) {
         return;
@@ -4303 +4311 @@
     $spaces = wp_spaces_regexp();
 
-    // Begin first "subpattern"
+    // Begin first "subpattern".
     $wp_smiliessearch = '/(?<=' . $spaces . '|^)';
 
@@ -4311 +4319 @@
         $rest      = substr( $smiley, 1 );
 
-        // new subpattern?
+        // New subpattern?
         if ( $firstchar != $subchar ) {
             if ( $subchar != '' ) {
-                $wp_smiliessearch .= ')(?=' . $spaces . '|$)';  // End previous "subpattern"
-                $wp_smiliessearch .= '|(?<=' . $spaces . '|^)'; // Begin another "subpattern"
+                $wp_smiliessearch .= ')(?=' . $spaces . '|$)';  // End previous "subpattern".
+                $wp_smiliessearch .= '|(?<=' . $spaces . '|^)'; // Begin another "subpattern".
             }
             $subchar           = $firstchar;
@@ -5349 +5357 @@
         $script_filename_dir = dirname( $_SERVER['SCRIPT_FILENAME'] );
 
-        // The request is for the admin
+        // The request is for the admin.
         if ( strpos( $_SERVER['REQUEST_URI'], 'wp-admin' ) !== false || strpos( $_SERVER['REQUEST_URI'], 'wp-login.php' ) !== false ) {
             $path = preg_replace( '#/(wp-admin/.*|wp-login.php)#i', '', $_SERVER['REQUEST_URI'] );
 
-            // The request is for a file in ABSPATH
+            // The request is for a file in ABSPATH.
         } elseif ( $script_filename_dir . '/' == $abspath_fix ) {
-            // Strip off any file/query params in the path
+            // Strip off any file/query params in the path.
             $path = preg_replace( '#/[^/]*$#i', '', $_SERVER['PHP_SELF'] );
 
         } else {
             if ( false !== strpos( $_SERVER['SCRIPT_FILENAME'], $abspath_fix ) ) {
-                // Request is hitting a file inside ABSPATH
+                // Request is hitting a file inside ABSPATH.
                 $directory = str_replace( ABSPATH, '', $script_filename_dir );
-                // Strip off the sub directory, and any file/query params
+                // Strip off the subdirectory, and any file/query params.
                 $path = preg_replace( '#/' . preg_quote( $directory, '#' ) . '/[^/]*$#i', '', $_SERVER['REQUEST_URI'] );
             } elseif ( false !== strpos( $abspath_fix, $script_filename_dir ) ) {
-                // Request is hitting a file above ABSPATH
+                // Request is hitting a file above ABSPATH.
                 $subdirectory = substr( $abspath_fix, strpos( $abspath_fix, $script_filename_dir ) + strlen( $script_filename_dir ) );
-                // Strip off any file/query params from the path, appending the sub directory to the installation
+                // Strip off any file/query params from the path, appending the subdirectory to the installation.
                 $path = preg_replace( '#/[^/]*$#i', '', $_SERVER['REQUEST_URI'] ) . $subdirectory;
             } else {
@@ -5374 +5382 @@
         }
 
-        $schema = is_ssl() ? 'https://' : 'http://'; // set_url_scheme() is not defined yet
+        $schema = is_ssl() ? 'https://' : 'http://'; // set_url_scheme() is not defined yet.
         $url    = $schema . $_SERVER['HTTP_HOST'] . $path;
     }
@@ -5642 +5650 @@
  */
 function _wp_timezone_choice_usort_callback( $a, $b ) {
-    // Don't use translated versions of Etc
+    // Don't use translated versions of Etc.
     if ( 'Etc' === $a['continent'] && 'Etc' === $b['continent'] ) {
-        // Make the order of these more like the old dropdown
+        // Make the order of these more like the old dropdown.
         if ( 'GMT+' === substr( $a['city'], 0, 4 ) && 'GMT+' === substr( $b['city'], 0, 4 ) ) {
             return -1 * ( strnatcasecmp( $a['city'], $b['city'] ) );
@@ -5668 +5676 @@
         return strnatcasecmp( $a['t_city'], $b['t_city'] );
     } else {
-        // Force Etc to the bottom of the list
+        // Force Etc to the bottom of the list.
         if ( 'Etc' === $a['continent'] ) {
             return 1;
@@ -5713 +5721 @@
         }
 
-        // This determines what gets set and translated - we don't translate Etc/* strings here, they are done later
+        // This determines what gets set and translated - we don't translate Etc/* strings here, they are done later.
         $exists    = array(
             0 => ( isset( $zone[0] ) && $zone[0] ),
@@ -5743 +5751 @@
 
     foreach ( $zonen as $key => $zone ) {
-        // Build value in an array to join later
+        // Build value in an array to join later.
         $value = array( $zone['continent'] );
 
         if ( empty( $zone['city'] ) ) {
-            // It's at the continent level (generally won't happen)
+            // It's at the continent level (generally won't happen).
             $display = $zone['t_continent'];
         } else {
-            // It's inside a continent group
-
-            // Continent optgroup
+            // It's inside a continent group.
+
+            // Continent optgroup.
             if ( ! isset( $zonen[ $key - 1 ] ) || $zonen[ $key - 1 ]['continent'] !== $zone['continent'] ) {
                 $label       = $zone['t_continent'];
@@ -5758 +5766 @@
             }
 
-            // Add the city to the value
+            // Add the city to the value.
             $value[] = $zone['city'];
 
             $display = $zone['t_city'];
             if ( ! empty( $zone['subcity'] ) ) {
-                // Add the subcity to the value
+                // Add the subcity to the value.
                 $value[]  = $zone['subcity'];
                 $display .= ' - ' . $zone['t_subcity'];
@@ -5769 +5777 @@
         }
 
-        // Build the value
+        // Build the value.
         $value    = join( '/', $value );
         $selected = '';
@@ -5777 +5785 @@
         $structure[] = '<option ' . $selected . 'value="' . esc_attr( $value ) . '">' . esc_html( $display ) . '</option>';
 
-        // Close continent optgroup
+        // Close continent optgroup.
         if ( ! empty( $zone['city'] ) && ( ! isset( $zonen[ $key + 1 ] ) || ( isset( $zonen[ $key + 1 ] ) && $zonen[ $key + 1 ]['continent'] !== $zone['continent'] ) ) ) {
             $structure[] = '</optgroup>';
@@ -5783 +5791 @@
     }
 
-    // Do UTC
+    // Do UTC.
     $structure[] = '<optgroup label="' . esc_attr__( 'UTC' ) . '">';
     $selected    = '';
@@ -5792 +5800 @@
     $structure[] = '</optgroup>';
 
-    // Do manual UTC offsets
+    // Do manual UTC offsets.
     $structure[]  = '<optgroup label="' . esc_attr__( 'Manual Offsets' ) . '">';
     $offset_range = array(
@@ -5986 +5994 @@
     $extra_headers = $context ? apply_filters( "extra_{$context}_headers", array() ) : array();
     if ( $extra_headers ) {
-        $extra_headers = array_combine( $extra_headers, $extra_headers ); // keys equal values
+        $extra_headers = array_combine( $extra_headers, $extra_headers ); // Keys equal values.
         $all_headers   = array_merge( $extra_headers, (array) $default_headers );
     } else {
@@ -6175 +6183 @@
     $return          = array();
 
-    // Set evanescent_hare to one past hare
-    // Increment hare two steps
+    // Set evanescent_hare to one past hare.
+    // Increment hare two steps.
     while (
         $tortoise
@@ -6190 +6198 @@
         }
 
-        // tortoise got lapped - must be a loop
+        // Tortoise got lapped - must be a loop.
         if ( $tortoise == $evanescent_hare || $tortoise == $hare ) {
             return $_return_loop ? $return : $tortoise;
         }
 
-        // Increment tortoise by one step
+        // Increment tortoise by one step.
         $tortoise = isset( $override[ $tortoise ] ) ? $override[ $tortoise ] : call_user_func_array( $callback, array_merge( array( $tortoise ), $callback_args ) );
     }
@@ -6278 +6286 @@
     $caller      = array();
     $check_class = ! is_null( $ignore_class );
-    $skip_frames++; // skip this function
+    $skip_frames++; // Skip this function.
 
     if ( ! isset( $truncate_paths ) ) {
@@ -6292 +6300 @@
         } elseif ( isset( $call['class'] ) ) {
             if ( $check_class && $ignore_class == $call['class'] ) {
-                continue; // Filter out calls
+                continue; // Filter out calls.
             }
 
@@ -6372 +6380 @@
 
     if ( false === $scheme_separator ) {
-        // $path isn't a stream
+        // $path isn't a stream.
         return false;
     }
@@ -6723 +6731 @@
     }
 
-    // Has to match the window name used in post_submit_meta_box()
+    // Has to match the window name used in post_submit_meta_box().
     $name = 'wp-preview-' . (int) $post->ID;
 
@@ -7013 +7021 @@
     );
 
-    // get site name
+    // Get site name.
     $site_name = wp_specialchars_decode( get_option( 'blogname' ), ENT_QUOTES );
 
@@ -7460 +7468 @@
     }
 
-    // Exclude individual site directories from the total when checking the main site of a network
+    // Exclude individual site directories from the total when checking the main site of a network,
     // as they are subdirectories and should not be counted.
     if ( is_multisite() && is_main_site() ) {