Make WordPress Core

Changeset 56191


Ignore:
Timestamp:
07/10/2023 10:36:06 PM (9 months 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.