WordPress.org
Get WordPress

Make WordPress Core

Changeset 56194


Ignore:
Timestamp:
07/10/2023 11:09:16 PM (14 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], [56191], [56192], [56193].

Props costdev, audrasjb.
See #58459.

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

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-includes/rewrite.php

    r55988 r56194  
    599599    foreach ( (array) $rewrite as $match => $query ) {
    600600
    601         // If the requesting file is the anchor of the match,
    602         // prepend it to the path info.
     601        /*
     602         * If the requesting file is the anchor of the match,
     603         * prepend it to the path info.
     604         */
    603605        if ( ! empty( $url ) && ( $url != $request ) && str_starts_with( $match, $url ) ) {
    604606            $request_match = $url . '/' . $request;
    … …  
    621623            }
    622624
    623             // Got a match.
    624             // Trim the query of everything up to the '?'.
     625            /*
     626             * Got a match.
     627             * Trim the query of everything up to the '?'.
     628             */
    625629            $query = preg_replace( '!^.+\?!', '', $query );
    626630

  • trunk/src/wp-includes/script-loader.php

    r56139 r56194  
    5858        && false !== stripos( $_SERVER['HTTP_ACCEPT_ENCODING'], 'gzip' ) && ! $force_uncompressed;
    5959
    60     // Load tinymce.js when running from /src, otherwise load wp-tinymce.js.gz (in production)
    61     // or tinymce.min.js (when SCRIPT_DEBUG is true).
     60    /*
     61     * Load tinymce.js when running from /src, otherwise load wp-tinymce.js.gz (in production)
     62     * or tinymce.min.js (when SCRIPT_DEBUG is true).
     63     */
    6264    if ( $compressed ) {
    6365        $scripts->add( 'wp-tinymce', includes_url( 'js/tinymce/' ) . 'wp-tinymce.js', array(), $tinymce_version );
    … …  
    586588    $tinymce_settings = apply_filters( 'tiny_mce_before_init', $tinymce_settings, 'classic-block' );
    587589
    588     // Do "by hand" translation from PHP array to js object.
    589     // Prevents breakage in some custom settings.
     590    /*
     591     * Do "by hand" translation from PHP array to js object.
     592     * Prevents breakage in some custom settings.
     593     */
    590594    $init_obj = '';
    591595    foreach ( $tinymce_settings as $key => $value ) {
    … …  
    826830    $scripts->add( 'cropper', '/wp-includes/js/crop/cropper.js', array( 'scriptaculous-dragdrop' ) );
    827831
    828     // jQuery.
    829     // The unminified jquery.js and jquery-migrate.js are included to facilitate debugging.
     832    /*
     833     * jQuery.
     834     * The unminified jquery.js and jquery-migrate.js are included to facilitate debugging.
     835     */
    830836    $scripts->add( 'jquery', false, array( 'jquery-core', 'jquery-migrate' ), '3.7.0' );
    831837    $scripts->add( 'jquery-core', "/wp-includes/js/jquery/jquery$suffix.js", array(), '3.7.0' );
    832838    $scripts->add( 'jquery-migrate', "/wp-includes/js/jquery/jquery-migrate$suffix.js", array(), '3.4.1' );
    833839
    834     // Full jQuery UI.
    835     // The build process in 1.12.1 has changed significantly.
    836     // In order to keep backwards compatibility, and to keep the optimized loading,
    837     // the source files were flattened and included with some modifications for AMD loading.
    838     // A notable change is that 'jquery-ui-core' now contains 'jquery-ui-position' and 'jquery-ui-widget'.
     840    /*
     841     * Full jQuery UI.
     842     * The build process in 1.12.1 has changed significantly.
     843     * In order to keep backwards compatibility, and to keep the optimized loading,
     844     * the source files were flattened and included with some modifications for AMD loading.
     845     * A notable change is that 'jquery-ui-core' now contains 'jquery-ui-position' and 'jquery-ui-widget'.
     846     */
    839847    $scripts->add( 'jquery-ui-core', "/wp-includes/js/jquery/ui/core$suffix.js", array( 'jquery' ), '1.13.2', 1 );
    840848    $scripts->add( 'jquery-effects-core', "/wp-includes/js/jquery/ui/effect$suffix.js", array( 'jquery' ), '1.13.2', 1 );
    … …  
    882890    $scripts->add( 'jquery-ui-sortable', "/wp-includes/js/jquery/ui/sortable$suffix.js", array( 'jquery-ui-mouse' ), '1.13.2', 1 );
    883891
    884     // As of 1.12.1 `jquery-ui-position` and `jquery-ui-widget` are part of `jquery-ui-core`.
    885     // Listed here for back-compat.
     892    /*
     893     * As of 1.12.1 `jquery-ui-position` and `jquery-ui-widget` are part of `jquery-ui-core`.
     894     * Listed here for back-compat.
     895     */
    886896    $scripts->add( 'jquery-ui-position', false, array( 'jquery-ui-core' ), '1.13.2', 1 );
    887897    $scripts->add( 'jquery-ui-widget', false, array( 'jquery-ui-core' ), '1.13.2', 1 );
    … …  
    916926    $scripts->add( 'suggest', "/wp-includes/js/jquery/suggest$suffix.js", array( 'jquery' ), '1.1-20110113', 1 );
    917927
    918     // Masonry v2 depended on jQuery. v3 does not. The older jquery-masonry handle is a shiv.
    919     // It sets jQuery as a dependency, as the theme may have been implicitly loading it this way.
     928    /*
     929     * Masonry v2 depended on jQuery. v3 does not. The older jquery-masonry handle is a shiv.
     930     * It sets jQuery as a dependency, as the theme may have been implicitly loading it this way.
     931     */
    920932    $scripts->add( 'imagesloaded', '/wp-includes/js/imagesloaded.min.js', array(), '4.1.4', 1 );
    921933    $scripts->add( 'masonry', '/wp-includes/js/masonry.min.js', array( 'imagesloaded' ), '4.2.2', 1 );
    … …  
    13391351    $scripts->add( 'wp-embed', "/wp-includes/js/wp-embed$suffix.js", array(), false, 1 );
    13401352
    1341     // To enqueue media-views or media-editor, call wp_enqueue_media().
    1342     // Both rely on numerous settings, styles, and templates to operate correctly.
     1353    /*
     1354     * To enqueue media-views or media-editor, call wp_enqueue_media().
     1355     * Both rely on numerous settings, styles, and templates to operate correctly.
     1356     */
    13431357    $scripts->add( 'media-views', "/wp-includes/js/media-views$suffix.js", array( 'utils', 'media-models', 'wp-plupload', 'jquery-ui-sortable', 'wp-mediaelement', 'wp-api-request', 'wp-a11y', 'clipboard' ), false, 1 );
    13441358    $scripts->set_translations( 'media-views' );
    … …  
    16361650        'wp-components',
    16371651        'wp-editor',
    1638         // This need to be added before the block library styles,
    1639         // The block library styles override the "reset" styles.
     1652        /*
     1653         * This needs to be added before the block library styles,
     1654         * The block library styles override the "reset" styles.
     1655         */
    16401656        'wp-reset-editor-styles',
    16411657        'wp-block-library',
    … …  
    27152731    $attributes_string    = '';
    27162732
    2717     // If HTML5 script tag is supported, only the attribute name is added
    2718     // to $attributes_string for entries with a boolean value, and that are true.
     2733    /*
     2734     * If HTML5 script tag is supported, only the attribute name is added
     2735     * to $attributes_string for entries with a boolean value, and that are true.
     2736     */
    27192737    foreach ( $attributes as $attribute_name => $attribute_value ) {
    27202738        if ( is_bool( $attribute_value ) ) {
    … …  
    28972915            $style['css'] = file_get_contents( $style['path'] );
    28982916
    2899             // Check if the style contains relative URLs that need to be modified.
    2900             // URLs relative to the stylesheet's path should be converted to relative to the site's root.
     2917            /*
     2918             * Check if the style contains relative URLs that need to be modified.
     2919             * URLs relative to the stylesheet's path should be converted to relative to the site's root.
     2920             */
    29012921            $style['css'] = _wp_normalize_relative_css_links( $style['css'], $style['src'] );
    29022922
    … …  
    37113731    $classic_theme_styles = ABSPATH . WPINC . "/css/classic-themes$suffix.css";
    37123732
    3713     // This follows the pattern of get_block_editor_theme_styles,
    3714     // but we can't use get_block_editor_theme_styles directly as it
    3715     // only handles external files or theme files.
     3733    /*
     3734     * This follows the pattern of get_block_editor_theme_styles,
     3735     * but we can't use get_block_editor_theme_styles directly as it
     3736     * only handles external files or theme files.
     3737     */
    37163738    $classic_theme_styles_settings = array(
    37173739        'css'            => file_get_contents( $classic_theme_styles ),

  • trunk/src/wp-includes/shortcodes.php

    r55990 r56194  
    264264    $tagregexp = implode( '|', array_map( 'preg_quote', $tagnames ) );
    265265
    266     // WARNING! Do not change this regex without changing do_shortcode_tag() and strip_shortcode_tag().
    267     // Also, see shortcode_unautop() and shortcode.js.
     266    /*
     267     * WARNING! Do not change this regex without changing do_shortcode_tag() and strip_shortcode_tag().
     268     * Also, see shortcode_unautop() and shortcode.js.
     269     */
    268270
    269271    // phpcs:disable Squiz.Strings.ConcatenationSpacing.PaddingFound -- don't remove regex indentation
    … …  
    467469                $attr = preg_replace_callback( "/$pattern/", 'do_shortcode_tag', $attr );
    468470            } else {
    469                 // $attr like 'name = "[shortcode]"' or "name = '[shortcode]'".
    470                 // We do not know if $content was unfiltered. Assume KSES ran before shortcodes.
     471                /*
     472                 * $attr like 'name = "[shortcode]"' or "name = '[shortcode]'".
     473                 * We do not know if $content was unfiltered. Assume KSES ran before shortcodes.
     474                 */
    471475                $count    = 0;
    472476                $new_attr = preg_replace_callback( "/$pattern/", 'do_shortcode_tag', $attr, -1, $count );

  • trunk/src/wp-includes/taxonomy.php

    r55921 r56194  
    32513251    $duplicate = get_term_by( 'slug', $slug, $taxonomy );
    32523252    if ( $duplicate && $duplicate->term_id !== $term_id ) {
    3253         // If an empty slug was passed or the parent changed, reset the slug to something unique.
    3254         // Otherwise, bail.
     3253        /*
     3254         * If an empty slug was passed or the parent changed, reset the slug to something unique.
     3255         * Otherwise, bail.
     3256         */
    32553257        if ( $empty_slug || ( $parent !== (int) $term['parent'] ) ) {
    32563258            $slug = wp_unique_term_slug( $slug, (object) $args );

  • trunk/src/wp-includes/template.php

    r55988 r56194  
    471471
    472472    if ( ! $pagename && $id ) {
    473         // If a static page is set as the front page, $pagename will not be set.
    474         // Retrieve it from the queried object.
     473        /*
     474         * If a static page is set as the front page, $pagename will not be set.
     475         * Retrieve it from the queried object.
     476         */
    475477        $post = get_queried_object();
    476478        if ( $post ) {

  • trunk/src/wp-includes/theme-templates.php

    r55365 r56194  
    174174        }
    175175
    176         // Get the site wrapper.
    177         // The skip-link will be injected in the beginning of it.
     176        /*
     177         * Get the site wrapper.
     178         * The skip-link will be injected in the beginning of it.
     179         */
    178180        sibling = document.querySelector( '.wp-site-blocks' );
    179181

  • trunk/src/wp-includes/theme.php

    r56142 r56194  
    4646
    4747    if ( is_array( $wp_theme_directories ) && count( $wp_theme_directories ) > 1 ) {
    48         // Make sure the active theme wins out, in case search_theme_directories() picks the wrong
    49         // one in the case of a conflict. (Normally, last registered theme root wins.)
     48        /*
     49         * Make sure the active theme wins out, in case search_theme_directories() picks the wrong
     50         * one in the case of a conflict. (Normally, last registered theme root wins.)
     51         */
    5052        $current_theme = get_stylesheet();
    5153        if ( isset( $theme_directories[ $current_theme ] ) ) {
    … …  
    511513            }
    512514            if ( file_exists( $theme_root . '/' . $dir . '/style.css' ) ) {
    513                 // wp-content/themes/a-single-theme
    514                 // wp-content/themes is $theme_root, a-single-theme is $dir.
     515                /*
     516                 * wp-content/themes/a-single-theme
     517                 * wp-content/themes is $theme_root, a-single-theme is $dir.
     518                 */
    515519                $found_themes[ $dir ] = array(
    516520                    'theme_file' => $dir . '/style.css',
    … …  
    519523            } else {
    520524                $found_theme = false;
    521                 // wp-content/themes/a-folder-of-themes/*
    522                 // wp-content/themes is $theme_root, a-folder-of-themes is $dir, then themes are $sub_dirs.
     525                /*
     526                 * wp-content/themes/a-folder-of-themes/*
     527                 * wp-content/themes is $theme_root, a-folder-of-themes is $dir, then themes are $sub_dirs.
     528                 */
    523529                $sub_dirs = @ scandir( $theme_root . '/' . $dir );
    524530                if ( ! $sub_dirs ) {
    … …  
    539545                    $found_theme                           = true;
    540546                }
    541                 // Never mind the above, it's just a theme missing a style.css.
    542                 // Return it; WP_Theme will catch the error.
     547                /*
     548                 * Never mind the above, it's just a theme missing a style.css.
     549                 * Return it; WP_Theme will catch the error.
     550                 */
    543551                if ( ! $found_theme ) {
    544552                    $found_themes[ $dir ] = array(
    … …  
    588596        $theme_root = get_raw_theme_root( $stylesheet_or_template );
    589597        if ( $theme_root ) {
    590             // Always prepend WP_CONTENT_DIR unless the root currently registered as a theme directory.
    591             // This gives relative theme roots the benefit of the doubt when things go haywire.
     598            /*
     599             * Always prepend WP_CONTENT_DIR unless the root currently registered as a theme directory.
     600             * This gives relative theme roots the benefit of the doubt when things go haywire.
     601             */
    592602            if ( ! in_array( $theme_root, (array) $wp_theme_directories, true ) ) {
    593603                $theme_root = WP_CONTENT_DIR . $theme_root;
    … …  
    18331843    $background = set_url_scheme( get_background_image() );
    18341844
    1835     // $color is the saved custom color.
    1836     // A default has to be specified in style.css. It will not be printed here.
     1845    /*
     1846     * $color is the saved custom color.
     1847     * A default has to be specified in style.css. It will not be printed here.
     1848     */
    18371849    $color = get_background_color();
    18381850
    … …  
    25082520                break;
    25092521
    2510             // All that's left now are posts (besides attachments).
    2511             // Not a default case for the sake of clarity and future work.
     2522            /*
     2523             * All that's left now are posts (besides attachments).
     2524             * Not a default case for the sake of clarity and future work.
     2525             */
    25122526            case 'posts':
    25132527                foreach ( $config[ $type ] as $id => $item ) {
    … …  
    27362750            unset( $args[0]['__jit'] );
    27372751
    2738             // Merge in data from previous add_theme_support() calls.
    2739             // The first value registered wins. (A child theme is set up first.)
     2752            /*
     2753             * Merge in data from previous add_theme_support() calls.
     2754             * The first value registered wins. (A child theme is set up first.)
     2755             */
    27402756            if ( isset( $_wp_theme_features['custom-header'] ) ) {
    27412757                $args[0] = wp_parse_args( $_wp_theme_features['custom-header'][0], $args[0] );
    27422758            }
    27432759
    2744             // Load in the defaults at the end, as we need to insure first one wins.
    2745             // This will cause all constants to be defined, as each arg will then be set to the default.
     2760            /*
     2761             * Load in the defaults at the end, as we need to insure first one wins.
     2762             * This will cause all constants to be defined, as each arg will then be set to the default.
     2763             */
    27462764            if ( $jit ) {
    27472765                $args[0] = wp_parse_args( $args[0], $defaults );
    … …  
    27902808            }
    27912809
    2792             // If headers are supported, and we still don't have a defined width or height,
    2793             // we have implicit flex sizes.
     2810            /*
     2811             * If headers are supported, and we still don't have a defined width or height,
     2812             * we have implicit flex sizes.
     2813             */
    27942814            if ( $jit ) {
    27952815                if ( empty( $args[0]['width'] ) && empty( $args[0]['flex-width'] ) ) {
    … …  
    34883508    $messenger_channel = null;
    34893509
    3490     // Value false indicates UUID should be determined after_setup_theme
    3491     // to either re-use existing saved changeset or else generate a new UUID if none exists.
     3510    /*
     3511     * Value false indicates UUID should be determined after_setup_theme
     3512     * to either re-use existing saved changeset or else generate a new UUID if none exists.
     3513     */
    34923514    $changeset_uuid = false;
    34933515
    3494     // Set initially fo false since defaults to true for back-compat;
    3495     // can be overridden via the customize_changeset_branching filter.
     3516    /*
     3517     * Set initially fo false since defaults to true for back-compat;
     3518     * can be overridden via the customize_changeset_branching filter.
     3519     */
    34963520    $branching = false;
    34973521

  • trunk/src/wp-includes/user.php

    r56151 r56194  
    10661066    }
    10671067
    1068     // Technically not needed, but does save calls to get_site() and get_user_meta()
    1069     // in the event that the function is called when a user isn't logged in.
     1068    /*
     1069     * Technically not needed, but does save calls to get_site() and get_user_meta()
     1070     * in the event that the function is called when a user isn't logged in.
     1071     */
    10701072    if ( empty( $user_id ) ) {
    10711073        return false;
    … …  
    27242726            wp_clear_auth_cookie();
    27252727
    2726             // Here we calculate the expiration length of the current auth cookie and compare it to the default expiration.
    2727             // If it's greater than this, then we know the user checked 'Remember Me' when they logged in.
     2728            /*
     2729             * Here we calculate the expiration length of the current auth cookie and compare it to the default expiration.
     2730             * If it's greater than this, then we know the user checked 'Remember Me' when they logged in.
     2731             */
    27282732            $logged_in_cookie = wp_parse_auth_cookie( '', 'logged_in' );
    27292733            /** This filter is documented in wp-includes/pluggable.php */

  • trunk/src/wp-includes/widgets.php

    r55990 r56194  
    186186        }
    187187
    188         // Custom specified ID's are suffixed if they exist already.
    189         // Automatically generated sidebar names need to be suffixed regardless starting at -0.
     188        /*
     189         * Custom specified ID's are suffixed if they exist already.
     190         * Automatically generated sidebar names need to be suffixed regardless starting at -0.
     191         */
    190192        if ( isset( $args['id'] ) ) {
    191193            $_args['id'] = $args['id'];
    … …  
    10141016    global $_wp_sidebars_widgets, $sidebars_widgets;
    10151017
    1016     // If loading from front page, consult $_wp_sidebars_widgets rather than options
    1017     // to see if wp_convert_widget_settings() has made manipulations in memory.
     1018    /*
     1019     * If loading from front page, consult $_wp_sidebars_widgets rather than options
     1020     * to see if wp_convert_widget_settings() has made manipulations in memory.
     1021     */
    10181022    if ( ! is_admin() ) {
    10191023        if ( empty( $_wp_sidebars_widgets ) ) {
Note: See TracChangeset for help on using the changeset viewer.