Make WordPress Core

Changeset 56191


Ignore:
Timestamp:
07/10/2023 10:36:06 PM (3 years ago)
Author:
audrasjb
Message:

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.

Location:
trunk/src/wp-includes
Files:
8 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/formatting.php

    r56132 r56191  
    137137                $static_replacements = array_merge( array( '…', $opening_quote, $closing_quote, ' ™' ), $cockneyreplace );
    138138
    139                 // Pattern-based replacements of characters.
    140                 // Sort the remaining patterns into several arrays for performance tuning.
     139                /*
     140                 * Pattern-based replacements of characters.
     141                 * Sort the remaining patterns into several arrays for performance tuning.
     142                 */
    141143                $dynamic_characters   = array(
    142144                        'apos'  => array(),
    … …  
    341343                                                $pos = strrpos( $sentence, "$flag." );
    342344                                        } else {
    343                                                 // When all else fails, make the rightmost candidate a closing quote.
    344                                                 // This is most likely to be problematic in the context of bug #18549.
     345                                                /*
     346                                                 * When all else fails, make the rightmost candidate a closing quote.
     347                                                 * This is most likely to be problematic in the context of bug #18549.
     348                                                 */
    345349                                                $pos = strrpos( $sentence, $flag );
    346350                                        }
    … …  
    977981
    978982        if ( ! $double_encode ) {
    979                 // Guarantee every &entity; is valid, convert &garbage; into &garbage;
    980                 // This is required for PHP < 5.4.0 because ENT_HTML401 flag is unavailable.
     983                /*
     984                 * Guarantee every &entity; is valid, convert &garbage; into &amp;garbage;
     985                 * This is required for PHP < 5.4.0 because ENT_HTML401 flag is unavailable.
     986                 */
    981987                $text = wp_kses_normalize_entities( $text, ( $quote_style & ENT_XML1 ) ? 'xml' : 'html' );
    982988        }
    … …  
    16021608        if ( seems_utf8( $text ) ) {
    16031609
    1604                 // Unicode sequence normalization from NFD (Normalization Form Decomposed)
    1605                 // to NFC (Normalization Form [Pre]Composed), the encoding used in this function.
     1610                /*
     1611                 * Unicode sequence normalization from NFD (Normalization Form Decomposed)
     1612                 * to NFC (Normalization Form [Pre]Composed), the encoding used in this function.
     1613                 */
    16061614                if ( function_exists( 'normalizer_is_normalized' )
    16071615                        && function_exists( 'normalizer_normalize' )
    … …  
    18181826                        // GBP (Pound) sign.
    18191827                        '£' => '',
    1820                         // Vowels with diacritic (Vietnamese).
    1821                         // Unmarked.
     1828                        // Vowels with diacritic (Vietnamese). Unmarked.
    18221829                        'Ơ' => 'O',
    18231830                        'ơ' => 'o',
    … …  
    26622669                        }
    26632670                } else { // Begin tag.
    2664                         if ( $has_self_closer ) { // If it presents itself as a self-closing tag...
    2665                                 // ...but it isn't a known single-entity self-closing tag, then don't let it be treated as such
    2666                                 // and immediately close it with a closing tag (the tag will encapsulate no text as a result).
     2671                        if ( $has_self_closer ) {
     2672                                /*
     2673                                 * If it presents itself as a self-closing tag, but it isn't a known single-entity self-closing tag,
     2674                                 * then don't let it be treated as such and immediately close it with a closing tag.
     2675                                 * The tag will encapsulate no text as a result.
     2676                                 */
    26672677                                if ( ! $is_single_tag ) {
    26682678                                        $attributes = trim( substr( $attributes, 0, -1 ) ) . "></$tag";
    26692679                                }
    2670                         } elseif ( $is_single_tag ) { // Else if it's a known single-entity tag but it doesn't close itself, do so.
     2680                        } elseif ( $is_single_tag ) {
     2681                                // Else if it's a known single-entity tag but it doesn't close itself, do so.
    26712682                                $pre_attribute_ws = ' ';
    26722683                                $attributes      .= '/';
    2673                         } else { // It's not a single-entity tag.
    2674                                 // If the top of the stack is the same as the tag we want to push, close previous tag.
     2684                        } else {
     2685                                /*
     2686                                 * It's not a single-entity tag.
     2687                                 * If the top of the stack is the same as the tag we want to push, close previous tag.
     2688                                 */
    26752689                                if ( $stacksize > 0 && ! in_array( $tag, $nestable_tags, true ) && $tagstack[ $stacksize - 1 ] === $tag ) {
    26762690                                        $tagqueue = '</' . array_pop( $tagstack ) . '>';
    … …  
    29262940
    29272941        if ( ')' === $matches[3] && strpos( $url, '(' ) ) {
    2928                 // If the trailing character is a closing parethesis, and the URL has an opening parenthesis in it,
    2929                 // add the closing parenthesis to the URL. Then we can let the parenthesis balancer do its thing below.
     2942                /*
     2943                 * If the trailing character is a closing parethesis, and the URL has an opening parenthesis in it,
     2944                 * add the closing parenthesis to the URL. Then we can let the parenthesis balancer do its thing below.
     2945                 */
    29302946                $url   .= $matches[3];
    29312947                $suffix = '';
    … …  
    31073123                                (\)?)                                          # 3: Trailing closing parenthesis (for parethesis balancing post processing).
    31083124                        ~xS';
    3109                         // The regex is a non-anchored pattern and does not have a single fixed starting character.
    3110                         // Tell PCRE to spend more time optimizing since, when used on a page load, it will probably be used several times.
     3125                        /*
     3126                         * The regex is a non-anchored pattern and does not have a single fixed starting character.
     3127                         * Tell PCRE to spend more time optimizing since, when used on a page load, it will probably be used several times.
     3128                         */
    31113129
    31123130                        $ret = preg_replace_callback( $url_clickable, '_make_url_clickable_cb', $ret );
    … …  
    35573575        list( $local, $domain ) = explode( '@', $email, 2 );
    35583576
    3559         // LOCAL PART
    3560         // Test for invalid characters.
     3577        /*
     3578         * LOCAL PART
     3579         * Test for invalid characters.
     3580         */
    35613581        if ( ! preg_match( '/^[a-zA-Z0-9!#$%&\'*+\/=?^_`{|}~\.-]+$/', $local ) ) {
    35623582                /** This filter is documented in wp-includes/formatting.php */
    … …  
    35643584        }
    35653585
    3566         // DOMAIN PART
    3567         // Test for sequences of periods.
     3586        /*
     3587         * DOMAIN PART
     3588         * Test for sequences of periods.
     3589         */
    35683590        if ( preg_match( '/\.{2,}/', $domain ) ) {
    35693591                /** This filter is documented in wp-includes/formatting.php */
    … …  
    37673789        list( $local, $domain ) = explode( '@', $email, 2 );
    37683790
    3769         // LOCAL PART
    3770         // Test for invalid characters.
     3791        /*
     3792         * LOCAL PART
     3793         * Test for invalid characters.
     3794         */
    37713795        $local = preg_replace( '/[^a-zA-Z0-9!#$%&\'*+\/=?^_`{|}~\.-]/', '', $local );
    37723796        if ( '' === $local ) {
    … …  
    37753799        }
    37763800
    3777         // DOMAIN PART
    3778         // Test for sequences of periods.
     3801        /*
     3802         * DOMAIN PART
     3803         * Test for sequences of periods.
     3804         */
    37793805        $domain = preg_replace( '/\.{2,}/', '', $domain );
    37803806        if ( '' === $domain ) {
  • trunk/src/wp-includes/functions.php

    r56115 r56191  
    37983798                $dir_attr       = "dir='$text_direction'";
    37993799
    3800                 // If `text_direction` was not explicitly passed,
    3801                 // use get_language_attributes() if available.
     3800                /*
     3801                 * If `text_direction` was not explicitly passed,
     3802                 * use get_language_attributes() if available.
     3803                 */
    38023804                if ( empty( $args['text_direction'] )
    38033805                        && function_exists( 'language_attributes' ) && function_exists( 'is_rtl' )
    … …  
    50865088 */
    50875089function _wp_to_kebab_case( $input_string ) {
    5088         //phpcs:disable WordPress.NamingConventions.ValidVariableName.VariableNotSnakeCase
    5089         // ignore the camelCase names for variables so the names are the same as lodash
    5090         // so comparing and porting new changes is easier.
     5090        // Ignore the camelCase names for variables so the names are the same as lodash so comparing and porting new changes is easier.
     5091        // phpcs:disable WordPress.NamingConventions.ValidVariableName.VariableNotSnakeCase
    50915092
    50925093        /*
    … …  
    68986899        $return          = array();
    68996900
    6900         // Set evanescent_hare to one past hare.
    6901         // Increment hare two steps.
     6901        // Set evanescent_hare to one past hare. Increment hare two steps.
    69026902        while (
    69036903                $tortoise
    … …  
    83508350function get_dirsize( $directory, $max_execution_time = null ) {
    83518351
    8352         // Exclude individual site directories from the total when checking the main site of a network,
    8353         // as they are subdirectories and should not be counted.
     8352        /*
     8353         * Exclude individual site directories from the total when checking the main site of a network,
     8354         * as they are subdirectories and should not be counted.
     8355         */
    83548356        if ( is_multisite() && is_main_site() ) {
    83558357                $size = recurse_dirsize( $directory, $directory . '/sites', $max_execution_time );
  • trunk/src/wp-includes/https-detection.php

    r55988 r56191  
    5050 */
    5151function wp_is_site_url_using_https() {
    52         // Use direct option access for 'siteurl' and manually run the 'site_url'
    53         // filter because `site_url()` will adjust the scheme based on what the
    54         // current request is using.
     52        /*
     53         * Use direct option access for 'siteurl' and manually run the 'site_url'
     54         * filter because `site_url()` will adjust the scheme based on what the
     55         * current request is using.
     56         */
    5557        /** This filter is documented in wp-includes/link-template.php */
    5658        $site_url = apply_filters( 'site_url', get_option( 'siteurl' ), '', null, null );
  • trunk/src/wp-includes/https-migration.php

    r50131 r56191  
    9898
    9999        if ( ! wp_is_using_https() ) {
    100                 // If this did not result in the site recognizing HTTPS as being used,
    101                 // revert the change and return false.
     100                /*
     101                 * If this did not result in the site recognizing HTTPS as being used,
     102                 * revert the change and return false.
     103                 */
    102104                update_option( 'home', $orig_home );
    103105                update_option( 'siteurl', $orig_siteurl );
  • trunk/src/wp-includes/kses.php

    r56046 r56191  
    792792                $value = $split[1];
    793793
    794                 // Remove quotes surrounding $value.
    795                 // Also guarantee correct quoting in $attr for this one attribute.
     794                /*
     795                 * Remove quotes surrounding $value.
     796                 * Also guarantee correct quoting in $attr for this one attribute.
     797                 */
    796798                if ( '' === $value ) {
    797799                        $quote = '';
    … …  
    14431445
    14441446        if ( 1 == $mode && false === array_key_exists( $attrname, $attrarr ) ) {
    1445                 // Special case, for when the attribute list ends with a valueless
    1446                 // attribute like "selected".
     1447                /*
     1448                 * Special case, for when the attribute list ends with a valueless
     1449                 * attribute like "selected".
     1450                 */
    14471451                $attrarr[ $attrname ] = array(
    14481452                        'name'  => $attrname,
    … …  
    15471551        // phpcs:enable
    15481552
    1549         // Although it is possible to reduce this procedure to a single regexp,
    1550         // we must run that regexp twice to get exactly the expected result.
     1553        /*
     1554         * Although it is possible to reduce this procedure to a single regexp,
     1555         * we must run that regexp twice to get exactly the expected result.
     1556         */
    15511557
    15521558        $validation = "%^($regex)+$%";
  • trunk/src/wp-includes/link-template.php

    r56053 r56191  
    250250                                }
    251251                        }
    252                         // Show default category in permalinks,
    253                         // without having to assign it explicitly.
     252                        /*
     253                         * Show default category in permalinks,
     254                         * without having to assign it explicitly.
     255                         */
    254256                        if ( empty( $category ) ) {
    255257                                $default_category = get_term( get_option( 'default_category' ), 'category' );
    … …  
    266268                }
    267269
    268                 // This is not an API call because the permalink is based on the stored post_date value,
    269                 // which should be parsed as local time regardless of the default PHP timezone.
     270                /*
     271                 * This is not an API call because the permalink is based on the stored post_date value,
     272                 * which should be parsed as local time regardless of the default PHP timezone.
     273                 */
    270274                $date = explode( ' ', str_replace( array( '-', ':' ), ' ', $post->post_date ) );
    271275
  • trunk/src/wp-includes/media.php

    r56164 r56191  
    218218        $img_url_basename = wp_basename( $img_url );
    219219
    220         // If the file isn't an image, attempt to replace its URL with a rendered image from its meta.
    221         // Otherwise, a non-image type could be returned.
     220        /*
     221         * If the file isn't an image, attempt to replace its URL with a rendered image from its meta.
     222         * Otherwise, a non-image type could be returned.
     223         */
    222224        if ( ! $is_image ) {
    223225                if ( ! empty( $meta['sizes']['full'] ) ) {
    … …  
    653655        }
    654656
    655         // The return array matches the parameters to imagecopyresampled().
    656         // int dst_x, int dst_y, int src_x, int src_y, int dst_w, int dst_h, int src_w, int src_h
     657        /*
     658         * The return array matches the parameters to imagecopyresampled().
     659         * int dst_x, int dst_y, int src_x, int src_y, int dst_w, int dst_h, int src_w, int src_h
     660         */
    657661        return array( 0, 0, (int) $s_x, (int) $s_y, (int) $new_w, (int) $new_h, (int) $crop_w, (int) $crop_h );
    658662}
    … …  
    10781082                }
    10791083
    1080                 // If the default value of `lazy` for the `loading` attribute is overridden
    1081                 // to omit the attribute for this image, ensure it is not included.
     1084                /*
     1085                 * If the default value of `lazy` for the `loading` attribute is overridden
     1086                 * to omit the attribute for this image, ensure it is not included.
     1087                 */
    10821088                if ( isset( $attr['loading'] ) && ! $attr['loading'] ) {
    10831089                        unset( $attr['loading'] );
    … …  
    17601766 */
    17611767function wp_lazy_loading_enabled( $tag_name, $context ) {
    1762         // By default add to all 'img' and 'iframe' tags.
    1763         // See https://html.spec.whatwg.org/multipage/embedded-content.html#attr-img-loading
    1764         // See https://html.spec.whatwg.org/multipage/iframe-embed-object.html#attr-iframe-loading
     1768        /*
     1769         * By default add to all 'img' and 'iframe' tags.
     1770         * See https://html.spec.whatwg.org/multipage/embedded-content.html#attr-img-loading
     1771         * See https://html.spec.whatwg.org/multipage/iframe-embed-object.html#attr-iframe-loading
     1772         */
    17651773        $default = ( 'img' === $tag_name || 'iframe' === $tag_name );
    17661774
    … …  
    18261834
    18271835                                        if ( $attachment_id ) {
    1828                                                 // If exactly the same image tag is used more than once, overwrite it.
    1829                                                 // All identical tags will be replaced later with 'str_replace()'.
     1836                                                /*
     1837                                                 * If exactly the same image tag is used more than once, overwrite it.
     1838                                                 * All identical tags will be replaced later with 'str_replace()'.
     1839                                                 */
    18301840                                                $images[ $tag ] = $attachment_id;
    18311841                                                break;
    … …  
    20412051 */
    20422052function wp_img_tag_add_decoding_attr( $image, $context ) {
    2043         // Only apply the decoding attribute to images that have a src attribute that
    2044         // starts with a double quote, ensuring escaped JSON is also excluded.
     2053        /*
     2054         * Only apply the decoding attribute to images that have a src attribute that
     2055         * starts with a double quote, ensuring escaped JSON is also excluded.
     2056         */
    20452057        if ( ! str_contains( $image, ' src="' ) ) {
    20462058                return $image;
    … …  
    21592171 */
    21602172function wp_iframe_tag_add_loading_attr( $iframe, $context ) {
    2161         // Iframes with fallback content (see `wp_filter_oembed_result()`) should not be lazy-loaded because they are
    2162         // visually hidden initially.
     2173        /*
     2174         * Iframes with fallback content (see `wp_filter_oembed_result()`) should not be lazy-loaded because they are
     2175         * visually hidden initially.
     2176         */
    21632177        if ( str_contains( $iframe, ' data-secret="' ) ) {
    21642178                return $iframe;
    21652179        }
    21662180
    2167         // Get loading attribute value to use. This must occur before the conditional check below so that even iframes that
    2168         // are ineligible for being lazy-loaded are considered.
     2181        /*
     2182         * Get loading attribute value to use. This must occur before the conditional check below so that even iframes that
     2183         * are ineligible for being lazy-loaded are considered.
     2184         */
    21692185        $optimization_attrs = wp_get_loading_optimization_attributes(
    21702186                'iframe',
    … …  
    35233539        }
    35243540
    3525         // MediaElement.js has issues with some URL formats for Vimeo and YouTube,
    3526         // so update the URL to prevent the ME.js player from breaking.
     3541        /*
     3542         * MediaElement.js has issues with some URL formats for Vimeo and YouTube,
     3543         * so update the URL to prevent the ME.js player from breaking.
     3544         */
    35273545        if ( 'mediaelement' === $library ) {
    35283546                if ( $is_youtube ) {
    … …  
    39914009                $file_info = wp_check_filetype( $args['path'] );
    39924010
    3993                 // If $file_info['type'] is false, then we let the editor attempt to
    3994                 // figure out the file type, rather than forcing a failure based on extension.
     4011                /*
     4012                 * If $file_info['type'] is false, then we let the editor attempt to
     4013                 * figure out the file type, rather than forcing a failure based on extension.
     4014                 */
    39954015                if ( isset( $file_info ) && $file_info['type'] ) {
    39964016                        $args['mime_type'] = $file_info['type'];
    … …  
    40894109                        ! call_user_func( array( $implementation, 'supports_mime_type' ), $args['output_mime_type'] )
    40904110                ) {
    4091                         // This implementation supports the imput type but not the output type.
    4092                         // Keep looking to see if we can find an implementation that supports both.
     4111                        /*
     4112                         * This implementation supports the imput type but not the output type.
     4113                         * Keep looking to see if we can find an implementation that supports both.
     4114                         */
    40934115                        $supports_input = $implementation;
    40944116                        continue;
    … …  
    43834405                                $size_meta = $meta['sizes'][ $size ];
    43844406
    4385                                 // We have the actual image size, but might need to further constrain it if content_width is narrower.
    4386                                 // Thumbnail, medium, and full sizes are also checked against the site's height/width options.
     4407                                /*
     4408                                 * We have the actual image size, but might need to further constrain it if content_width is narrower.
     4409                                 * Thumbnail, medium, and full sizes are also checked against the site's height/width options.
     4410                                 */
    43874411                                list( $width, $height ) = image_constrain_size_for_editor( $size_meta['width'], $size_meta['height'], $size, 'edit' );
    43884412
    … …  
    45144538        $args     = wp_parse_args( $args, $defaults );
    45154539
    4516         // We're going to pass the old thickbox media tabs to `media_upload_tabs`
    4517         // to ensure plugins will work. We will then unset those tabs.
     4540        /*
     4541         * We're going to pass the old thickbox media tabs to `media_upload_tabs`
     4542         * to ensure plugins will work. We will then unset those tabs.
     4543         */
    45184544        $tabs = array(
    45194545                // handler action suffix => tab label
    … …  
    48594885        $strings['settings'] = $settings;
    48604886
    4861         // Ensure we enqueue media-editor first, that way media-views
    4862         // is registered internally before we try to localize it. See #24724.
     4887        /*
     4888         * Ensure we enqueue media-editor first, that way media-views
     4889         * is registered internally before we try to localize it. See #24724.
     4890         */
    48634891        wp_enqueue_script( 'media-editor' );
    48644892        wp_localize_script( 'media-views', '_wpMediaViewsL10n', $strings );
    … …  
    54555483        }
    54565484
    5457         // For PHP versions that don't support WebP images,
    5458         // extract the image size info from the file headers.
     5485        /*
     5486         * For PHP versions that don't support WebP images,
     5487         * extract the image size info from the file headers.
     5488         */
    54595489        if ( 'image/webp' === wp_get_image_mime( $filename ) ) {
    54605490                $webp_info = wp_get_webp_info( $filename );
    … …  
    55175547        }
    55185548
    5519         // The headers are a little different for each of the three formats.
    5520         // Header values based on WebP docs, see https://developers.google.com/speed/webp/docs/riff_container.
     5549        /*
     5550         * The headers are a little different for each of the three formats.
     5551         * Header values based on WebP docs, see https://developers.google.com/speed/webp/docs/riff_container.
     5552         */
    55215553        switch ( substr( $magic, 12, 4 ) ) {
    55225554                // Lossy WebP.
  • trunk/src/wp-includes/meta.php

    r55826 r56191  
    911911                $object_id    = $meta->{$column};
    912912
    913                 // If a new meta_key (last parameter) was specified, change the meta key,
    914                 // otherwise use the original key in the update statement.
     913                /*
     914                 * If a new meta_key (last parameter) was specified, change the meta key,
     915                 * otherwise use the original key in the update statement.
     916                 */
    915917                if ( false === $meta_key ) {
    916918                        $meta_key = $original_key;
Note: See TracChangeset for help on using the changeset viewer.