From 321158f72632bf4b833e21d451f4e124f7f24f05 Mon Sep 17 00:00:00 2001 From: audrasjb Date: Mon, 10 Jul 2023 22:38:25 +0000 Subject: [PATCH] Docs: Replace multiple single line comments with multi-line comments. This changeset updates various comments as per WordPress PHP Inline Documentation Standards. See https://developer.wordpress.org/coding-standards/inline-documentation-standards/php/#5-inline-comments. Follow-up to [56174], [56175], [56176], [56177], [56178], [56179], [56180]. Props costdev, audrasjb. See #58459. Built from https://develop.svn.wordpress.org/trunk@56191 git-svn-id: http://core.svn.wordpress.org/trunk@55703 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-includes/formatting.php | 82 +++++++++++++++++---------- wp-includes/functions.php | 20 ++++--- wp-includes/https-detection.php | 8 ++- wp-includes/https-migration.php | 6 +- wp-includes/kses.php | 18 ++++-- wp-includes/link-template.php | 12 ++-- wp-includes/media.php | 98 ++++++++++++++++++++++----------- wp-includes/meta.php | 6 +- wp-includes/version.php | 2 +- 9 files changed, 164 insertions(+), 88 deletions(-) diff --git a/wp-includes/formatting.php b/wp-includes/formatting.php index 50b43a5175..a3e35599c0 100644 --- a/wp-includes/formatting.php +++ b/wp-includes/formatting.php @@ -136,8 +136,10 @@ function wptexturize( $text, $reset = false ) { $static_characters = array_merge( array( '...', '``', '\'\'', ' (tm)' ), $cockney ); $static_replacements = array_merge( array( '…', $opening_quote, $closing_quote, ' ™' ), $cockneyreplace ); - // Pattern-based replacements of characters. - // Sort the remaining patterns into several arrays for performance tuning. + /* + * Pattern-based replacements of characters. + * Sort the remaining patterns into several arrays for performance tuning. + */ $dynamic_characters = array( 'apos' => array(), 'quote' => array(), @@ -340,8 +342,10 @@ function wptexturize_primes( $haystack, $needle, $prime, $open_quote, $close_quo // Assume the rightmost quote-period match is the end of quotation. $pos = strrpos( $sentence, "$flag." ); } else { - // When all else fails, make the rightmost candidate a closing quote. - // This is most likely to be problematic in the context of bug #18549. + /* + * When all else fails, make the rightmost candidate a closing quote. + * This is most likely to be problematic in the context of bug #18549. + */ $pos = strrpos( $sentence, $flag ); } $sentence = substr_replace( $sentence, $close_quote, $pos, strlen( $flag ) ); @@ -976,8 +980,10 @@ function _wp_specialchars( $text, $quote_style = ENT_NOQUOTES, $charset = false, } if ( ! $double_encode ) { - // Guarantee every &entity; is valid, convert &garbage; into &garbage; - // This is required for PHP < 5.4.0 because ENT_HTML401 flag is unavailable. + /* + * Guarantee every &entity; is valid, convert &garbage; into &garbage; + * This is required for PHP < 5.4.0 because ENT_HTML401 flag is unavailable. + */ $text = wp_kses_normalize_entities( $text, ( $quote_style & ENT_XML1 ) ? 'xml' : 'html' ); } @@ -1601,8 +1607,10 @@ function remove_accents( $text, $locale = '' ) { if ( seems_utf8( $text ) ) { - // Unicode sequence normalization from NFD (Normalization Form Decomposed) - // to NFC (Normalization Form [Pre]Composed), the encoding used in this function. + /* + * Unicode sequence normalization from NFD (Normalization Form Decomposed) + * to NFC (Normalization Form [Pre]Composed), the encoding used in this function. + */ if ( function_exists( 'normalizer_is_normalized' ) && function_exists( 'normalizer_normalize' ) ) { @@ -1817,8 +1825,7 @@ function remove_accents( $text, $locale = '' ) { '€' => 'E', // GBP (Pound) sign. '£' => '', - // Vowels with diacritic (Vietnamese). - // Unmarked. + // Vowels with diacritic (Vietnamese). Unmarked. 'Ơ' => 'O', 'ơ' => 'o', 'Ư' => 'U', @@ -2661,17 +2668,24 @@ function force_balance_tags( $text ) { $tag = ''; } } else { // Begin tag. - if ( $has_self_closer ) { // If it presents itself as a self-closing tag... - // ...but it isn't a known single-entity self-closing tag, then don't let it be treated as such - // and immediately close it with a closing tag (the tag will encapsulate no text as a result). + if ( $has_self_closer ) { + /* + * If it presents itself as a self-closing tag, but it isn't a known single-entity self-closing tag, + * then don't let it be treated as such and immediately close it with a closing tag. + * The tag will encapsulate no text as a result. + */ if ( ! $is_single_tag ) { $attributes = trim( substr( $attributes, 0, -1 ) ) . "> 0 && ! in_array( $tag, $nestable_tags, true ) && $tagstack[ $stacksize - 1 ] === $tag ) { $tagqueue = ''; $stacksize--; @@ -2925,8 +2939,10 @@ function _make_url_clickable_cb( $matches ) { $url = $matches[2]; if ( ')' === $matches[3] && strpos( $url, '(' ) ) { - // If the trailing character is a closing parethesis, and the URL has an opening parenthesis in it, - // add the closing parenthesis to the URL. Then we can let the parenthesis balancer do its thing below. + /* + * If the trailing character is a closing parethesis, and the URL has an opening parenthesis in it, + * add the closing parenthesis to the URL. Then we can let the parenthesis balancer do its thing below. + */ $url .= $matches[3]; $suffix = ''; } else { @@ -3106,8 +3122,10 @@ function make_clickable( $text ) { ) (\)?) # 3: Trailing closing parenthesis (for parethesis balancing post processing). ~xS'; - // The regex is a non-anchored pattern and does not have a single fixed starting character. - // Tell PCRE to spend more time optimizing since, when used on a page load, it will probably be used several times. + /* + * The regex is a non-anchored pattern and does not have a single fixed starting character. + * Tell PCRE to spend more time optimizing since, when used on a page load, it will probably be used several times. + */ $ret = preg_replace_callback( $url_clickable, '_make_url_clickable_cb', $ret ); @@ -3556,15 +3574,19 @@ function is_email( $email, $deprecated = false ) { // Split out the local and domain parts. list( $local, $domain ) = explode( '@', $email, 2 ); - // LOCAL PART - // Test for invalid characters. + /* + * LOCAL PART + * Test for invalid characters. + */ if ( ! preg_match( '/^[a-zA-Z0-9!#$%&\'*+\/=?^_`{|}~\.-]+$/', $local ) ) { /** This filter is documented in wp-includes/formatting.php */ return apply_filters( 'is_email', false, $email, 'local_invalid_chars' ); } - // DOMAIN PART - // Test for sequences of periods. + /* + * DOMAIN PART + * Test for sequences of periods. + */ if ( preg_match( '/\.{2,}/', $domain ) ) { /** This filter is documented in wp-includes/formatting.php */ return apply_filters( 'is_email', false, $email, 'domain_period_sequence' ); @@ -3766,16 +3788,20 @@ function sanitize_email( $email ) { // Split out the local and domain parts. list( $local, $domain ) = explode( '@', $email, 2 ); - // LOCAL PART - // Test for invalid characters. + /* + * LOCAL PART + * Test for invalid characters. + */ $local = preg_replace( '/[^a-zA-Z0-9!#$%&\'*+\/=?^_`{|}~\.-]/', '', $local ); if ( '' === $local ) { /** This filter is documented in wp-includes/formatting.php */ return apply_filters( 'sanitize_email', '', $email, 'local_invalid_chars' ); } - // DOMAIN PART - // Test for sequences of periods. + /* + * DOMAIN PART + * Test for sequences of periods. + */ $domain = preg_replace( '/\.{2,}/', '', $domain ); if ( '' === $domain ) { /** This filter is documented in wp-includes/formatting.php */ diff --git a/wp-includes/functions.php b/wp-includes/functions.php index 3267120b6f..164548c680 100644 --- a/wp-includes/functions.php +++ b/wp-includes/functions.php @@ -3797,8 +3797,10 @@ function _default_wp_die_handler( $message, $title = '', $args = array() ) { $text_direction = $parsed_args['text_direction']; $dir_attr = "dir='$text_direction'"; - // If `text_direction` was not explicitly passed, - // use get_language_attributes() if available. + /* + * If `text_direction` was not explicitly passed, + * use get_language_attributes() if available. + */ if ( empty( $args['text_direction'] ) && function_exists( 'language_attributes' ) && function_exists( 'is_rtl' ) ) { @@ -5085,9 +5087,8 @@ function _wp_array_set( &$input_array, $path, $value = null ) { * @return string kebab-cased-string. */ function _wp_to_kebab_case( $input_string ) { - //phpcs:disable WordPress.NamingConventions.ValidVariableName.VariableNotSnakeCase - // ignore the camelCase names for variables so the names are the same as lodash - // so comparing and porting new changes is easier. + // Ignore the camelCase names for variables so the names are the same as lodash so comparing and porting new changes is easier. + // phpcs:disable WordPress.NamingConventions.ValidVariableName.VariableNotSnakeCase /* * Some notable things we've removed compared to the lodash version are: @@ -6897,8 +6898,7 @@ function wp_find_hierarchy_loop_tortoise_hare( $callback, $start, $override = ar $evanescent_hare = $start; $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 && @@ -8349,8 +8349,10 @@ function wp_get_direct_update_https_url() { */ function get_dirsize( $directory, $max_execution_time = null ) { - // Exclude individual site directories from the total when checking the main site of a network, - // as they are subdirectories and should not be counted. + /* + * 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() ) { $size = recurse_dirsize( $directory, $directory . '/sites', $max_execution_time ); } else { diff --git a/wp-includes/https-detection.php b/wp-includes/https-detection.php index 955e4b7dde..878dd1aa38 100644 --- a/wp-includes/https-detection.php +++ b/wp-includes/https-detection.php @@ -49,9 +49,11 @@ function wp_is_home_url_using_https() { * @return bool True if using HTTPS, false otherwise. */ function wp_is_site_url_using_https() { - // Use direct option access for 'siteurl' and manually run the 'site_url' - // filter because `site_url()` will adjust the scheme based on what the - // current request is using. + /* + * Use direct option access for 'siteurl' and manually run the 'site_url' + * filter because `site_url()` will adjust the scheme based on what the + * current request is using. + */ /** This filter is documented in wp-includes/link-template.php */ $site_url = apply_filters( 'site_url', get_option( 'siteurl' ), '', null, null ); diff --git a/wp-includes/https-migration.php b/wp-includes/https-migration.php index b8b80d63f0..1232154bbc 100644 --- a/wp-includes/https-migration.php +++ b/wp-includes/https-migration.php @@ -97,8 +97,10 @@ function wp_update_urls_to_https() { update_option( 'siteurl', $siteurl ); if ( ! wp_is_using_https() ) { - // If this did not result in the site recognizing HTTPS as being used, - // revert the change and return false. + /* + * If this did not result in the site recognizing HTTPS as being used, + * revert the change and return false. + */ update_option( 'home', $orig_home ); update_option( 'siteurl', $orig_siteurl ); return false; diff --git a/wp-includes/kses.php b/wp-includes/kses.php index fd0d67dfed..31bc2b5e7a 100644 --- a/wp-includes/kses.php +++ b/wp-includes/kses.php @@ -791,8 +791,10 @@ function wp_kses_one_attr( $attr, $element ) { if ( count( $split ) === 2 ) { $value = $split[1]; - // Remove quotes surrounding $value. - // Also guarantee correct quoting in $attr for this one attribute. + /* + * Remove quotes surrounding $value. + * Also guarantee correct quoting in $attr for this one attribute. + */ if ( '' === $value ) { $quote = ''; } else { @@ -1442,8 +1444,10 @@ function wp_kses_hair( $attr, $allowed_protocols ) { } // End while. if ( 1 == $mode && false === array_key_exists( $attrname, $attrarr ) ) { - // Special case, for when the attribute list ends with a valueless - // attribute like "selected". + /* + * Special case, for when the attribute list ends with a valueless + * attribute like "selected". + */ $attrarr[ $attrname ] = array( 'name' => $attrname, 'value' => '', @@ -1546,8 +1550,10 @@ function wp_kses_hair_parse( $attr ) { . '\s*'; // Trailing space is optional except as mentioned above. // phpcs:enable - // Although it is possible to reduce this procedure to a single regexp, - // we must run that regexp twice to get exactly the expected result. + /* + * Although it is possible to reduce this procedure to a single regexp, + * we must run that regexp twice to get exactly the expected result. + */ $validation = "%^($regex)+$%"; $extraction = "%$regex%"; diff --git a/wp-includes/link-template.php b/wp-includes/link-template.php index 7fc1074470..5a09674622 100644 --- a/wp-includes/link-template.php +++ b/wp-includes/link-template.php @@ -249,8 +249,10 @@ function get_permalink( $post = 0, $leavename = false ) { $category = get_category_parents( $category_object->parent, false, '/', true ) . $category; } } - // Show default category in permalinks, - // without having to assign it explicitly. + /* + * Show default category in permalinks, + * without having to assign it explicitly. + */ if ( empty( $category ) ) { $default_category = get_term( get_option( 'default_category' ), 'category' ); if ( $default_category && ! is_wp_error( $default_category ) ) { @@ -265,8 +267,10 @@ function get_permalink( $post = 0, $leavename = false ) { $author = $authordata->user_nicename; } - // This is not an API call because the permalink is based on the stored post_date value, - // which should be parsed as local time regardless of the default PHP timezone. + /* + * This is not an API call because the permalink is based on the stored post_date value, + * which should be parsed as local time regardless of the default PHP timezone. + */ $date = explode( ' ', str_replace( array( '-', ':' ), ' ', $post->post_date ) ); $rewritereplace = array( diff --git a/wp-includes/media.php b/wp-includes/media.php index 234a826447..1dc610f550 100644 --- a/wp-includes/media.php +++ b/wp-includes/media.php @@ -217,8 +217,10 @@ function image_downsize( $id, $size = 'medium' ) { $is_intermediate = false; $img_url_basename = wp_basename( $img_url ); - // If the file isn't an image, attempt to replace its URL with a rendered image from its meta. - // Otherwise, a non-image type could be returned. + /* + * If the file isn't an image, attempt to replace its URL with a rendered image from its meta. + * Otherwise, a non-image type could be returned. + */ if ( ! $is_image ) { if ( ! empty( $meta['sizes']['full'] ) ) { $img_url = str_replace( $img_url_basename, $meta['sizes']['full']['file'], $img_url ); @@ -652,8 +654,10 @@ function image_resize_dimensions( $orig_w, $orig_h, $dest_w, $dest_h, $crop = fa } } - // The return array matches the parameters to imagecopyresampled(). - // int dst_x, int dst_y, int src_x, int src_y, int dst_w, int dst_h, int src_w, int src_h + /* + * The return array matches the parameters to imagecopyresampled(). + * int dst_x, int dst_y, int src_x, int src_y, int dst_w, int dst_h, int src_w, int src_h + */ return array( 0, 0, (int) $s_x, (int) $s_y, (int) $new_w, (int) $new_h, (int) $crop_w, (int) $crop_h ); } @@ -1077,8 +1081,10 @@ function wp_get_attachment_image( $attachment_id, $size = 'thumbnail', $icon = f unset( $attr['decoding'] ); } - // If the default value of `lazy` for the `loading` attribute is overridden - // to omit the attribute for this image, ensure it is not included. + /* + * If the default value of `lazy` for the `loading` attribute is overridden + * to omit the attribute for this image, ensure it is not included. + */ if ( isset( $attr['loading'] ) && ! $attr['loading'] ) { unset( $attr['loading'] ); } @@ -1759,9 +1765,11 @@ function wp_image_add_srcset_and_sizes( $image, $image_meta, $attachment_id ) { * @return bool Whether to add the attribute. */ function wp_lazy_loading_enabled( $tag_name, $context ) { - // By default add to all 'img' and 'iframe' tags. - // See https://html.spec.whatwg.org/multipage/embedded-content.html#attr-img-loading - // See https://html.spec.whatwg.org/multipage/iframe-embed-object.html#attr-iframe-loading + /* + * By default add to all 'img' and 'iframe' tags. + * See https://html.spec.whatwg.org/multipage/embedded-content.html#attr-img-loading + * See https://html.spec.whatwg.org/multipage/iframe-embed-object.html#attr-iframe-loading + */ $default = ( 'img' === $tag_name || 'iframe' === $tag_name ); /** @@ -1825,8 +1833,10 @@ function wp_filter_content_tags( $content, $context = null ) { $attachment_id = absint( $class_id[1] ); if ( $attachment_id ) { - // If exactly the same image tag is used more than once, overwrite it. - // All identical tags will be replaced later with 'str_replace()'. + /* + * If exactly the same image tag is used more than once, overwrite it. + * All identical tags will be replaced later with 'str_replace()'. + */ $images[ $tag ] = $attachment_id; break; } @@ -2040,8 +2050,10 @@ function wp_img_tag_add_loading_optimization_attrs( $image, $context ) { * @return string Converted `img` tag with `decoding` attribute added. */ function wp_img_tag_add_decoding_attr( $image, $context ) { - // Only apply the decoding attribute to images that have a src attribute that - // starts with a double quote, ensuring escaped JSON is also excluded. + /* + * Only apply the decoding attribute to images that have a src attribute that + * starts with a double quote, ensuring escaped JSON is also excluded. + */ if ( ! str_contains( $image, ' src="' ) ) { return $image; } @@ -2158,14 +2170,18 @@ function wp_img_tag_add_srcset_and_sizes_attr( $image, $context, $attachment_id * @return string Converted `iframe` tag with `loading` attribute added. */ function wp_iframe_tag_add_loading_attr( $iframe, $context ) { - // Iframes with fallback content (see `wp_filter_oembed_result()`) should not be lazy-loaded because they are - // visually hidden initially. + /* + * Iframes with fallback content (see `wp_filter_oembed_result()`) should not be lazy-loaded because they are + * visually hidden initially. + */ if ( str_contains( $iframe, ' data-secret="' ) ) { return $iframe; } - // Get loading attribute value to use. This must occur before the conditional check below so that even iframes that - // are ineligible for being lazy-loaded are considered. + /* + * Get loading attribute value to use. This must occur before the conditional check below so that even iframes that + * are ineligible for being lazy-loaded are considered. + */ $optimization_attrs = wp_get_loading_optimization_attributes( 'iframe', array( @@ -3522,8 +3538,10 @@ function wp_video_shortcode( $attr, $content = '' ) { wp_enqueue_script( 'mediaelement-vimeo' ); } - // MediaElement.js has issues with some URL formats for Vimeo and YouTube, - // so update the URL to prevent the ME.js player from breaking. + /* + * MediaElement.js has issues with some URL formats for Vimeo and YouTube, + * so update the URL to prevent the ME.js player from breaking. + */ if ( 'mediaelement' === $library ) { if ( $is_youtube ) { // Remove `feature` query arg and force SSL - see #40866. @@ -3990,8 +4008,10 @@ function wp_get_image_editor( $path, $args = array() ) { if ( ! isset( $args['mime_type'] ) ) { $file_info = wp_check_filetype( $args['path'] ); - // If $file_info['type'] is false, then we let the editor attempt to - // figure out the file type, rather than forcing a failure based on extension. + /* + * If $file_info['type'] is false, then we let the editor attempt to + * figure out the file type, rather than forcing a failure based on extension. + */ if ( isset( $file_info ) && $file_info['type'] ) { $args['mime_type'] = $file_info['type']; } @@ -4088,8 +4108,10 @@ function _wp_image_editor_choose( $args = array() ) { $args['mime_type'] !== $args['output_mime_type'] && ! call_user_func( array( $implementation, 'supports_mime_type' ), $args['output_mime_type'] ) ) { - // This implementation supports the imput type but not the output type. - // Keep looking to see if we can find an implementation that supports both. + /* + * This implementation supports the imput type but not the output type. + * Keep looking to see if we can find an implementation that supports both. + */ $supports_input = $implementation; continue; } @@ -4382,8 +4404,10 @@ function wp_prepare_attachment_for_js( $attachment ) { // Nothing from the filter, so consult image metadata if we have it. $size_meta = $meta['sizes'][ $size ]; - // We have the actual image size, but might need to further constrain it if content_width is narrower. - // Thumbnail, medium, and full sizes are also checked against the site's height/width options. + /* + * We have the actual image size, but might need to further constrain it if content_width is narrower. + * Thumbnail, medium, and full sizes are also checked against the site's height/width options. + */ list( $width, $height ) = image_constrain_size_for_editor( $size_meta['width'], $size_meta['height'], $size, 'edit' ); $sizes[ $size ] = array( @@ -4513,8 +4537,10 @@ function wp_enqueue_media( $args = array() ) { ); $args = wp_parse_args( $args, $defaults ); - // We're going to pass the old thickbox media tabs to `media_upload_tabs` - // to ensure plugins will work. We will then unset those tabs. + /* + * We're going to pass the old thickbox media tabs to `media_upload_tabs` + * to ensure plugins will work. We will then unset those tabs. + */ $tabs = array( // handler action suffix => tab label 'type' => '', @@ -4858,8 +4884,10 @@ function wp_enqueue_media( $args = array() ) { $strings['settings'] = $settings; - // Ensure we enqueue media-editor first, that way media-views - // is registered internally before we try to localize it. See #24724. + /* + * Ensure we enqueue media-editor first, that way media-views + * is registered internally before we try to localize it. See #24724. + */ wp_enqueue_script( 'media-editor' ); wp_localize_script( 'media-views', '_wpMediaViewsL10n', $strings ); @@ -5454,8 +5482,10 @@ function wp_getimagesize( $filename, array &$image_info = null ) { return $info; } - // For PHP versions that don't support WebP images, - // extract the image size info from the file headers. + /* + * For PHP versions that don't support WebP images, + * extract the image size info from the file headers. + */ if ( 'image/webp' === wp_get_image_mime( $filename ) ) { $webp_info = wp_get_webp_info( $filename ); $width = $webp_info['width']; @@ -5516,8 +5546,10 @@ function wp_get_webp_info( $filename ) { return compact( 'width', 'height', 'type' ); } - // The headers are a little different for each of the three formats. - // Header values based on WebP docs, see https://developers.google.com/speed/webp/docs/riff_container. + /* + * The headers are a little different for each of the three formats. + * Header values based on WebP docs, see https://developers.google.com/speed/webp/docs/riff_container. + */ switch ( substr( $magic, 12, 4 ) ) { // Lossy WebP. case 'VP8 ': diff --git a/wp-includes/meta.php b/wp-includes/meta.php index 2b5ca02696..0b9f08544e 100644 --- a/wp-includes/meta.php +++ b/wp-includes/meta.php @@ -910,8 +910,10 @@ function update_metadata_by_mid( $meta_type, $meta_id, $meta_value, $meta_key = $original_key = $meta->meta_key; $object_id = $meta->{$column}; - // If a new meta_key (last parameter) was specified, change the meta key, - // otherwise use the original key in the update statement. + /* + * If a new meta_key (last parameter) was specified, change the meta key, + * otherwise use the original key in the update statement. + */ if ( false === $meta_key ) { $meta_key = $original_key; } elseif ( ! is_string( $meta_key ) ) { diff --git a/wp-includes/version.php b/wp-includes/version.php index f6639ff967..0f773eba6b 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -16,7 +16,7 @@ * * @global string $wp_version */ -$wp_version = '6.3-beta3-56190'; +$wp_version = '6.3-beta3-56191'; /** * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.