From b89f155a10837227c76ca3663a8ecc6e44bbdc49 Mon Sep 17 00:00:00 2001 From: audrasjb Date: Mon, 10 Jul 2023 23:11:22 +0000 Subject: [PATCH] Docs: Replace multiple single line comments with multi-line comments. This changeset updates various comments as per WordPress PHP Inline Documentation Standards. See https://developer.wordpress.org/coding-standards/inline-documentation-standards/php/#5-inline-comments. Follow-up to [56174], [56175], [56176], [56177], [56178], [56179], [56180], [56191], [56192], [56193]. Props costdev, audrasjb. See #58459. Built from https://develop.svn.wordpress.org/trunk@56194 git-svn-id: http://core.svn.wordpress.org/trunk@55706 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-includes/rewrite.php | 12 ++++-- wp-includes/script-loader.php | 74 +++++++++++++++++++++------------ wp-includes/shortcodes.php | 12 ++++-- wp-includes/taxonomy.php | 6 ++- wp-includes/template.php | 6 ++- wp-includes/theme-templates.php | 6 ++- wp-includes/theme.php | 72 +++++++++++++++++++++----------- wp-includes/user.php | 12 ++++-- wp-includes/version.php | 2 +- wp-includes/widgets.php | 12 ++++-- 10 files changed, 141 insertions(+), 73 deletions(-) diff --git a/wp-includes/rewrite.php b/wp-includes/rewrite.php index 1198e520ff..b76de4c136 100644 --- a/wp-includes/rewrite.php +++ b/wp-includes/rewrite.php @@ -598,8 +598,10 @@ function url_to_postid( $url ) { $request_match = $request; foreach ( (array) $rewrite as $match => $query ) { - // If the requesting file is the anchor of the match, - // prepend it to the path info. + /* + * If the requesting file is the anchor of the match, + * prepend it to the path info. + */ if ( ! empty( $url ) && ( $url != $request ) && str_starts_with( $match, $url ) ) { $request_match = $url . '/' . $request; } @@ -620,8 +622,10 @@ function url_to_postid( $url ) { } } - // Got a match. - // Trim the query of everything up to the '?'. + /* + * Got a match. + * Trim the query of everything up to the '?'. + */ $query = preg_replace( '!^.+\?!', '', $query ); // Substitute the substring matches into the query. diff --git a/wp-includes/script-loader.php b/wp-includes/script-loader.php index 741e29ac18..c32e482109 100644 --- a/wp-includes/script-loader.php +++ b/wp-includes/script-loader.php @@ -57,8 +57,10 @@ function wp_register_tinymce_scripts( $scripts, $force_uncompressed = false ) { $compressed = $compress_scripts && $concatenate_scripts && isset( $_SERVER['HTTP_ACCEPT_ENCODING'] ) && false !== stripos( $_SERVER['HTTP_ACCEPT_ENCODING'], 'gzip' ) && ! $force_uncompressed; - // Load tinymce.js when running from /src, otherwise load wp-tinymce.js.gz (in production) - // or tinymce.min.js (when SCRIPT_DEBUG is true). + /* + * Load tinymce.js when running from /src, otherwise load wp-tinymce.js.gz (in production) + * or tinymce.min.js (when SCRIPT_DEBUG is true). + */ if ( $compressed ) { $scripts->add( 'wp-tinymce', includes_url( 'js/tinymce/' ) . 'wp-tinymce.js', array(), $tinymce_version ); } else { @@ -585,8 +587,10 @@ function wp_tinymce_inline_scripts() { /** This filter is documented in wp-includes/class-wp-editor.php */ $tinymce_settings = apply_filters( 'tiny_mce_before_init', $tinymce_settings, 'classic-block' ); - // Do "by hand" translation from PHP array to js object. - // Prevents breakage in some custom settings. + /* + * Do "by hand" translation from PHP array to js object. + * Prevents breakage in some custom settings. + */ $init_obj = ''; foreach ( $tinymce_settings as $key => $value ) { if ( is_bool( $value ) ) { @@ -825,17 +829,21 @@ function wp_default_scripts( $scripts ) { // Not used in core, replaced by Jcrop.js. $scripts->add( 'cropper', '/wp-includes/js/crop/cropper.js', array( 'scriptaculous-dragdrop' ) ); - // jQuery. - // The unminified jquery.js and jquery-migrate.js are included to facilitate debugging. + /* + * jQuery. + * The unminified jquery.js and jquery-migrate.js are included to facilitate debugging. + */ $scripts->add( 'jquery', false, array( 'jquery-core', 'jquery-migrate' ), '3.7.0' ); $scripts->add( 'jquery-core', "/wp-includes/js/jquery/jquery$suffix.js", array(), '3.7.0' ); $scripts->add( 'jquery-migrate', "/wp-includes/js/jquery/jquery-migrate$suffix.js", array(), '3.4.1' ); - // Full jQuery UI. - // The build process in 1.12.1 has changed significantly. - // In order to keep backwards compatibility, and to keep the optimized loading, - // the source files were flattened and included with some modifications for AMD loading. - // A notable change is that 'jquery-ui-core' now contains 'jquery-ui-position' and 'jquery-ui-widget'. + /* + * Full jQuery UI. + * The build process in 1.12.1 has changed significantly. + * In order to keep backwards compatibility, and to keep the optimized loading, + * the source files were flattened and included with some modifications for AMD loading. + * A notable change is that 'jquery-ui-core' now contains 'jquery-ui-position' and 'jquery-ui-widget'. + */ $scripts->add( 'jquery-ui-core', "/wp-includes/js/jquery/ui/core$suffix.js", array( 'jquery' ), '1.13.2', 1 ); $scripts->add( 'jquery-effects-core', "/wp-includes/js/jquery/ui/effect$suffix.js", array( 'jquery' ), '1.13.2', 1 ); @@ -881,8 +889,10 @@ function wp_default_scripts( $scripts ) { $scripts->add( 'jquery-ui-selectable', "/wp-includes/js/jquery/ui/selectable$suffix.js", array( 'jquery-ui-mouse' ), '1.13.2', 1 ); $scripts->add( 'jquery-ui-sortable', "/wp-includes/js/jquery/ui/sortable$suffix.js", array( 'jquery-ui-mouse' ), '1.13.2', 1 ); - // As of 1.12.1 `jquery-ui-position` and `jquery-ui-widget` are part of `jquery-ui-core`. - // Listed here for back-compat. + /* + * As of 1.12.1 `jquery-ui-position` and `jquery-ui-widget` are part of `jquery-ui-core`. + * Listed here for back-compat. + */ $scripts->add( 'jquery-ui-position', false, array( 'jquery-ui-core' ), '1.13.2', 1 ); $scripts->add( 'jquery-ui-widget', false, array( 'jquery-ui-core' ), '1.13.2', 1 ); @@ -915,8 +925,10 @@ function wp_default_scripts( $scripts ) { // Not used any more, registered for backward compatibility. $scripts->add( 'suggest', "/wp-includes/js/jquery/suggest$suffix.js", array( 'jquery' ), '1.1-20110113', 1 ); - // Masonry v2 depended on jQuery. v3 does not. The older jquery-masonry handle is a shiv. - // It sets jQuery as a dependency, as the theme may have been implicitly loading it this way. + /* + * Masonry v2 depended on jQuery. v3 does not. The older jquery-masonry handle is a shiv. + * It sets jQuery as a dependency, as the theme may have been implicitly loading it this way. + */ $scripts->add( 'imagesloaded', '/wp-includes/js/imagesloaded.min.js', array(), '4.1.4', 1 ); $scripts->add( 'masonry', '/wp-includes/js/masonry.min.js', array( 'imagesloaded' ), '4.2.2', 1 ); $scripts->add( 'jquery-masonry', '/wp-includes/js/jquery/jquery.masonry.min.js', array( 'jquery', 'masonry' ), '3.1.2b', 1 ); @@ -1338,8 +1350,10 @@ function wp_default_scripts( $scripts ) { $scripts->add( 'wp-embed', "/wp-includes/js/wp-embed$suffix.js", array(), false, 1 ); - // To enqueue media-views or media-editor, call wp_enqueue_media(). - // Both rely on numerous settings, styles, and templates to operate correctly. + /* + * To enqueue media-views or media-editor, call wp_enqueue_media(). + * Both rely on numerous settings, styles, and templates to operate correctly. + */ $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 ); $scripts->set_translations( 'media-views' ); @@ -1635,8 +1649,10 @@ function wp_default_styles( $styles ) { $wp_edit_blocks_dependencies = array( 'wp-components', 'wp-editor', - // This need to be added before the block library styles, - // The block library styles override the "reset" styles. + /* + * This needs to be added before the block library styles, + * The block library styles override the "reset" styles. + */ 'wp-reset-editor-styles', 'wp-block-library', 'wp-reusable-blocks', @@ -2714,8 +2730,10 @@ function wp_sanitize_script_attributes( $attributes ) { $html5_script_support = ! is_admin() && ! current_theme_supports( 'html5', 'script' ); $attributes_string = ''; - // If HTML5 script tag is supported, only the attribute name is added - // to $attributes_string for entries with a boolean value, and that are true. + /* + * If HTML5 script tag is supported, only the attribute name is added + * to $attributes_string for entries with a boolean value, and that are true. + */ foreach ( $attributes as $attribute_name => $attribute_value ) { if ( is_bool( $attribute_value ) ) { if ( $attribute_value ) { @@ -2896,8 +2914,10 @@ function wp_maybe_inline_styles() { // Get the styles if we don't already have them. $style['css'] = file_get_contents( $style['path'] ); - // Check if the style contains relative URLs that need to be modified. - // URLs relative to the stylesheet's path should be converted to relative to the site's root. + /* + * Check if the style contains relative URLs that need to be modified. + * URLs relative to the stylesheet's path should be converted to relative to the site's root. + */ $style['css'] = _wp_normalize_relative_css_links( $style['css'], $style['src'] ); // Set `src` to `false` and add styles inline. @@ -3710,9 +3730,11 @@ function wp_add_editor_classic_theme_styles( $editor_settings ) { $suffix = wp_scripts_get_suffix(); $classic_theme_styles = ABSPATH . WPINC . "/css/classic-themes$suffix.css"; - // This follows the pattern of get_block_editor_theme_styles, - // but we can't use get_block_editor_theme_styles directly as it - // only handles external files or theme files. + /* + * This follows the pattern of get_block_editor_theme_styles, + * but we can't use get_block_editor_theme_styles directly as it + * only handles external files or theme files. + */ $classic_theme_styles_settings = array( 'css' => file_get_contents( $classic_theme_styles ), '__unstableType' => 'core', diff --git a/wp-includes/shortcodes.php b/wp-includes/shortcodes.php index 79c780eca1..ea55f3373a 100644 --- a/wp-includes/shortcodes.php +++ b/wp-includes/shortcodes.php @@ -263,8 +263,10 @@ function get_shortcode_regex( $tagnames = null ) { } $tagregexp = implode( '|', array_map( 'preg_quote', $tagnames ) ); - // WARNING! Do not change this regex without changing do_shortcode_tag() and strip_shortcode_tag(). - // Also, see shortcode_unautop() and shortcode.js. + /* + * WARNING! Do not change this regex without changing do_shortcode_tag() and strip_shortcode_tag(). + * Also, see shortcode_unautop() and shortcode.js. + */ // phpcs:disable Squiz.Strings.ConcatenationSpacing.PaddingFound -- don't remove regex indentation return '\\[' // Opening bracket. @@ -466,8 +468,10 @@ function do_shortcodes_in_html_tags( $content, $ignore_html, $tagnames ) { */ $attr = preg_replace_callback( "/$pattern/", 'do_shortcode_tag', $attr ); } else { - // $attr like 'name = "[shortcode]"' or "name = '[shortcode]'". - // We do not know if $content was unfiltered. Assume KSES ran before shortcodes. + /* + * $attr like 'name = "[shortcode]"' or "name = '[shortcode]'". + * We do not know if $content was unfiltered. Assume KSES ran before shortcodes. + */ $count = 0; $new_attr = preg_replace_callback( "/$pattern/", 'do_shortcode_tag', $attr, -1, $count ); if ( $count > 0 ) { diff --git a/wp-includes/taxonomy.php b/wp-includes/taxonomy.php index 35031e3bef..52a5705331 100644 --- a/wp-includes/taxonomy.php +++ b/wp-includes/taxonomy.php @@ -3250,8 +3250,10 @@ function wp_update_term( $term_id, $taxonomy, $args = array() ) { // Check for duplicate slug. $duplicate = get_term_by( 'slug', $slug, $taxonomy ); if ( $duplicate && $duplicate->term_id !== $term_id ) { - // If an empty slug was passed or the parent changed, reset the slug to something unique. - // Otherwise, bail. + /* + * If an empty slug was passed or the parent changed, reset the slug to something unique. + * Otherwise, bail. + */ if ( $empty_slug || ( $parent !== (int) $term['parent'] ) ) { $slug = wp_unique_term_slug( $slug, (object) $args ); } else { diff --git a/wp-includes/template.php b/wp-includes/template.php index 6d89f2a23a..b9ac37d235 100644 --- a/wp-includes/template.php +++ b/wp-includes/template.php @@ -470,8 +470,10 @@ function get_page_template() { $pagename = get_query_var( 'pagename' ); if ( ! $pagename && $id ) { - // If a static page is set as the front page, $pagename will not be set. - // Retrieve it from the queried object. + /* + * If a static page is set as the front page, $pagename will not be set. + * Retrieve it from the queried object. + */ $post = get_queried_object(); if ( $post ) { $pagename = $post->post_name; diff --git a/wp-includes/theme-templates.php b/wp-includes/theme-templates.php index 7d053a6805..114d7205d4 100644 --- a/wp-includes/theme-templates.php +++ b/wp-includes/theme-templates.php @@ -173,8 +173,10 @@ function the_block_template_skip_link() { return; } - // Get the site wrapper. - // The skip-link will be injected in the beginning of it. + /* + * Get the site wrapper. + * The skip-link will be injected in the beginning of it. + */ sibling = document.querySelector( '.wp-site-blocks' ); // Early exit if the root element was not found. diff --git a/wp-includes/theme.php b/wp-includes/theme.php index dfc0a4e063..911c4a942b 100644 --- a/wp-includes/theme.php +++ b/wp-includes/theme.php @@ -45,8 +45,10 @@ function wp_get_themes( $args = array() ) { $theme_directories = search_theme_directories(); if ( is_array( $wp_theme_directories ) && count( $wp_theme_directories ) > 1 ) { - // Make sure the active theme wins out, in case search_theme_directories() picks the wrong - // one in the case of a conflict. (Normally, last registered theme root wins.) + /* + * Make sure the active theme wins out, in case search_theme_directories() picks the wrong + * one in the case of a conflict. (Normally, last registered theme root wins.) + */ $current_theme = get_stylesheet(); if ( isset( $theme_directories[ $current_theme ] ) ) { $root_of_current_theme = get_raw_theme_root( $current_theme ); @@ -510,16 +512,20 @@ function search_theme_directories( $force = false ) { continue; } if ( file_exists( $theme_root . '/' . $dir . '/style.css' ) ) { - // wp-content/themes/a-single-theme - // wp-content/themes is $theme_root, a-single-theme is $dir. + /* + * wp-content/themes/a-single-theme + * wp-content/themes is $theme_root, a-single-theme is $dir. + */ $found_themes[ $dir ] = array( 'theme_file' => $dir . '/style.css', 'theme_root' => $theme_root, ); } else { $found_theme = false; - // wp-content/themes/a-folder-of-themes/* - // wp-content/themes is $theme_root, a-folder-of-themes is $dir, then themes are $sub_dirs. + /* + * wp-content/themes/a-folder-of-themes/* + * wp-content/themes is $theme_root, a-folder-of-themes is $dir, then themes are $sub_dirs. + */ $sub_dirs = @ scandir( $theme_root . '/' . $dir ); if ( ! $sub_dirs ) { trigger_error( "$theme_root/$dir is not readable", E_USER_NOTICE ); @@ -538,8 +544,10 @@ function search_theme_directories( $force = false ) { ); $found_theme = true; } - // Never mind the above, it's just a theme missing a style.css. - // Return it; WP_Theme will catch the error. + /* + * Never mind the above, it's just a theme missing a style.css. + * Return it; WP_Theme will catch the error. + */ if ( ! $found_theme ) { $found_themes[ $dir ] = array( 'theme_file' => $dir . '/style.css', @@ -587,8 +595,10 @@ function get_theme_root( $stylesheet_or_template = '' ) { if ( $stylesheet_or_template ) { $theme_root = get_raw_theme_root( $stylesheet_or_template ); if ( $theme_root ) { - // Always prepend WP_CONTENT_DIR unless the root currently registered as a theme directory. - // This gives relative theme roots the benefit of the doubt when things go haywire. + /* + * Always prepend WP_CONTENT_DIR unless the root currently registered as a theme directory. + * This gives relative theme roots the benefit of the doubt when things go haywire. + */ if ( ! in_array( $theme_root, (array) $wp_theme_directories, true ) ) { $theme_root = WP_CONTENT_DIR . $theme_root; } @@ -1832,8 +1842,10 @@ function _custom_background_cb() { // $background is the saved custom image, or the default image. $background = set_url_scheme( get_background_image() ); - // $color is the saved custom color. - // A default has to be specified in style.css. It will not be printed here. + /* + * $color is the saved custom color. + * A default has to be specified in style.css. It will not be printed here. + */ $color = get_background_color(); if ( get_theme_support( 'custom-background', 'default-color' ) === $color ) { @@ -2507,8 +2519,10 @@ function get_theme_starter_content() { } break; - // All that's left now are posts (besides attachments). - // Not a default case for the sake of clarity and future work. + /* + * All that's left now are posts (besides attachments). + * Not a default case for the sake of clarity and future work. + */ case 'posts': foreach ( $config[ $type ] as $id => $item ) { if ( is_array( $item ) ) { @@ -2735,14 +2749,18 @@ function add_theme_support( $feature, ...$args ) { $jit = isset( $args[0]['__jit'] ); unset( $args[0]['__jit'] ); - // Merge in data from previous add_theme_support() calls. - // The first value registered wins. (A child theme is set up first.) + /* + * Merge in data from previous add_theme_support() calls. + * The first value registered wins. (A child theme is set up first.) + */ if ( isset( $_wp_theme_features['custom-header'] ) ) { $args[0] = wp_parse_args( $_wp_theme_features['custom-header'][0], $args[0] ); } - // Load in the defaults at the end, as we need to insure first one wins. - // This will cause all constants to be defined, as each arg will then be set to the default. + /* + * Load in the defaults at the end, as we need to insure first one wins. + * This will cause all constants to be defined, as each arg will then be set to the default. + */ if ( $jit ) { $args[0] = wp_parse_args( $args[0], $defaults ); } @@ -2789,8 +2807,10 @@ function add_theme_support( $feature, ...$args ) { $args[0]['random-default'] = false; } - // If headers are supported, and we still don't have a defined width or height, - // we have implicit flex sizes. + /* + * If headers are supported, and we still don't have a defined width or height, + * we have implicit flex sizes. + */ if ( $jit ) { if ( empty( $args[0]['width'] ) && empty( $args[0]['flex-width'] ) ) { $args[0]['flex-width'] = true; @@ -3487,12 +3507,16 @@ function _wp_customize_include() { $autosaved = null; $messenger_channel = null; - // Value false indicates UUID should be determined after_setup_theme - // to either re-use existing saved changeset or else generate a new UUID if none exists. + /* + * Value false indicates UUID should be determined after_setup_theme + * to either re-use existing saved changeset or else generate a new UUID if none exists. + */ $changeset_uuid = false; - // Set initially fo false since defaults to true for back-compat; - // can be overridden via the customize_changeset_branching filter. + /* + * Set initially fo false since defaults to true for back-compat; + * can be overridden via the customize_changeset_branching filter. + */ $branching = false; if ( $is_customize_admin_page && isset( $input_vars['changeset_uuid'] ) ) { diff --git a/wp-includes/user.php b/wp-includes/user.php index 55fb8605b4..9b25e49aa9 100644 --- a/wp-includes/user.php +++ b/wp-includes/user.php @@ -1065,8 +1065,10 @@ function is_user_member_of_blog( $user_id = 0, $blog_id = 0 ) { $user_id = get_current_user_id(); } - // Technically not needed, but does save calls to get_site() and get_user_meta() - // in the event that the function is called when a user isn't logged in. + /* + * Technically not needed, but does save calls to get_site() and get_user_meta() + * in the event that the function is called when a user isn't logged in. + */ if ( empty( $user_id ) ) { return false; } else { @@ -2723,8 +2725,10 @@ All at ###SITENAME### if ( isset( $plaintext_pass ) ) { wp_clear_auth_cookie(); - // Here we calculate the expiration length of the current auth cookie and compare it to the default expiration. - // If it's greater than this, then we know the user checked 'Remember Me' when they logged in. + /* + * Here we calculate the expiration length of the current auth cookie and compare it to the default expiration. + * If it's greater than this, then we know the user checked 'Remember Me' when they logged in. + */ $logged_in_cookie = wp_parse_auth_cookie( '', 'logged_in' ); /** This filter is documented in wp-includes/pluggable.php */ $default_cookie_life = apply_filters( 'auth_cookie_expiration', ( 2 * DAY_IN_SECONDS ), $user_id, false ); diff --git a/wp-includes/version.php b/wp-includes/version.php index 61e56124a7..e517b7564c 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -16,7 +16,7 @@ * * @global string $wp_version */ -$wp_version = '6.3-beta3-56193'; +$wp_version = '6.3-beta3-56194'; /** * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema. diff --git a/wp-includes/widgets.php b/wp-includes/widgets.php index 517299c493..c568cbe301 100644 --- a/wp-includes/widgets.php +++ b/wp-includes/widgets.php @@ -185,8 +185,10 @@ function register_sidebars( $number = 1, $args = array() ) { $_args['name'] = isset( $args['name'] ) ? $args['name'] : __( 'Sidebar' ); } - // Custom specified ID's are suffixed if they exist already. - // Automatically generated sidebar names need to be suffixed regardless starting at -0. + /* + * Custom specified ID's are suffixed if they exist already. + * Automatically generated sidebar names need to be suffixed regardless starting at -0. + */ if ( isset( $args['id'] ) ) { $_args['id'] = $args['id']; $n = 2; // Start at -2 for conflicting custom IDs. @@ -1013,8 +1015,10 @@ function wp_get_sidebars_widgets( $deprecated = true ) { global $_wp_sidebars_widgets, $sidebars_widgets; - // If loading from front page, consult $_wp_sidebars_widgets rather than options - // to see if wp_convert_widget_settings() has made manipulations in memory. + /* + * If loading from front page, consult $_wp_sidebars_widgets rather than options + * to see if wp_convert_widget_settings() has made manipulations in memory. + */ if ( ! is_admin() ) { if ( empty( $_wp_sidebars_widgets ) ) { $_wp_sidebars_widgets = get_option( 'sidebars_widgets', array() );