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
This commit is contained in:
audrasjb 2023-07-10 22:38:25 +00:00
parent cc24b1f950
commit 321158f726
9 changed files with 164 additions and 88 deletions

View File

@ -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 &amp;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 ) ) . "></$tag";
}
} elseif ( $is_single_tag ) { // Else if it's a known single-entity tag but it doesn't close itself, do so.
} elseif ( $is_single_tag ) {
// Else if it's a known single-entity tag but it doesn't close itself, do so.
$pre_attribute_ws = ' ';
$attributes .= '/';
} else { // It's not a single-entity tag.
// If the top of the stack is the same as the tag we want to push, close previous tag.
} else {
/*
* It's not a single-entity tag.
* If the top of the stack is the same as the tag we want to push, close previous tag.
*/
if ( $stacksize > 0 && ! in_array( $tag, $nestable_tags, true ) && $tagstack[ $stacksize - 1 ] === $tag ) {
$tagqueue = '</' . array_pop( $tagstack ) . '>';
$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 */

View File

@ -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 {

View File

@ -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 );

View File

@ -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;

View File

@ -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%";

View File

@ -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(

View File

@ -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 ':

View File

@ -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 ) ) {

View File

@ -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.