From 3beb1d25abc84061db46513b545a1387045f467d Mon Sep 17 00:00:00 2001 From: Sergey Biryukov Date: Fri, 10 Dec 2021 20:30:05 +0000 Subject: [PATCH] Docs: Correct the format of some comments per the documentation standards. Follow-up to [10357], [10939], [43309], [51003], [51266], [51653], [51738], [52110]. See #53399. Built from https://develop.svn.wordpress.org/trunk@52352 git-svn-id: http://core.svn.wordpress.org/trunk@51944 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-admin/includes/plugin.php | 6 +- wp-admin/load-scripts.php | 4 +- wp-admin/load-styles.php | 4 +- wp-includes/class-wp-customize-manager.php | 2 +- wp-includes/class-wp-customize-widgets.php | 5 +- wp-includes/default-filters.php | 2 +- wp-includes/functions.php | 83 ++++++++++++++++------ wp-includes/load.php | 4 +- wp-includes/template-canvas.php | 2 +- wp-includes/user.php | 8 +-- wp-includes/version.php | 2 +- 11 files changed, 79 insertions(+), 43 deletions(-) diff --git a/wp-admin/includes/plugin.php b/wp-admin/includes/plugin.php index 368aac9b03..c0ac17a881 100644 --- a/wp-admin/includes/plugin.php +++ b/wp-admin/includes/plugin.php @@ -2523,7 +2523,7 @@ function deactivated_plugins_notice() { foreach ( $deactivated_plugins as $plugin ) { if ( ! empty( $plugin['version_compatible'] ) && ! empty( $plugin['version_deactivated'] ) ) { $explanation = sprintf( - /* translators: 1: Name of deactivated plugin, 2: Plugin version deactivated, 3: Current WP version, 4: Compatible plugin version */ + /* translators: 1: Name of deactivated plugin, 2: Plugin version deactivated, 3: Current WP version, 4: Compatible plugin version. */ __( '%1$s %2$s was deactivated due to incompatibility with WordPress %3$s, please upgrade to %1$s %4$s or later.' ), $plugin['plugin_name'], $plugin['version_deactivated'], @@ -2532,7 +2532,7 @@ function deactivated_plugins_notice() { ); } else { $explanation = sprintf( - /* translators: 1: Name of deactivated plugin, 2: Plugin version deactivated, 3: Current WP version */ + /* translators: 1: Name of deactivated plugin, 2: Plugin version deactivated, 3: Current WP version. */ __( '%1$s %2$s was deactivated due to incompatibility with WordPress %3$s.' ), $plugin['plugin_name'], ! empty( $plugin['version_deactivated'] ) ? $plugin['version_deactivated'] : '', @@ -2544,7 +2544,7 @@ function deactivated_plugins_notice() { printf( '

%s
%s

%s

', sprintf( - /* translators: %s: Name of deactivated plugin */ + /* translators: %s: Name of deactivated plugin. */ __( '%s plugin deactivated during WordPress upgrade.' ), $plugin['plugin_name'] ), diff --git a/wp-admin/load-scripts.php b/wp-admin/load-scripts.php index f28721f7e4..7995471deb 100644 --- a/wp-admin/load-scripts.php +++ b/wp-admin/load-scripts.php @@ -1,13 +1,13 @@ components, $this ); diff --git a/wp-includes/class-wp-customize-widgets.php b/wp-includes/class-wp-customize-widgets.php index c96773b139..98a63b4112 100644 --- a/wp-includes/class-wp-customize-widgets.php +++ b/wp-includes/class-wp-customize-widgets.php @@ -1421,9 +1421,8 @@ final class WP_Customize_Widgets { if ( ! empty( $widget_object->widget_options['show_instance_in_rest'] ) ) { if ( 'block' === $id_base && ! current_user_can( 'unfiltered_html' ) ) { /* - * The content of the 'block' widget is not filtered on the - * fly while editing. Filter the content here to prevent - * vulnerabilities. + * The content of the 'block' widget is not filtered on the fly while editing. + * Filter the content here to prevent vulnerabilities. */ $value['raw_instance']['content'] = wp_kses_post( $value['raw_instance']['content'] ); } diff --git a/wp-includes/default-filters.php b/wp-includes/default-filters.php index 23b0035d8f..39c7119fbc 100644 --- a/wp-includes/default-filters.php +++ b/wp-includes/default-filters.php @@ -674,7 +674,7 @@ add_filter( 'user_has_cap', 'wp_maybe_grant_install_languages_cap', 1 ); add_filter( 'user_has_cap', 'wp_maybe_grant_resume_extensions_caps', 1 ); add_filter( 'user_has_cap', 'wp_maybe_grant_site_health_caps', 1, 4 ); -// Block Templates post type and Rendering +// Block templates post type and rendering. add_filter( 'render_block_context', '_block_template_render_without_post_block_context' ); add_filter( 'pre_wp_unique_post_slug', 'wp_filter_wp_template_unique_post_slug', 10, 5 ); add_action( 'save_post_wp_template_part', 'wp_set_unique_slug_on_create_template_part' ); diff --git a/wp-includes/functions.php b/wp-includes/functions.php index 424db545b2..cf85ac88c8 100644 --- a/wp-includes/functions.php +++ b/wp-includes/functions.php @@ -2538,8 +2538,10 @@ function wp_unique_filename( $dir, $filename, $unique_filename_callback = null ) $filename = str_replace( "{$fname}{$ext}", "{$fname}-{$number}{$ext}", $filename ); } - // Get the mime type. Uploaded files were already checked with wp_check_filetype_and_ext() - // in _wp_handle_upload(). Using wp_check_filetype() would be sufficient here. + /* + * Get the mime type. Uploaded files were already checked with wp_check_filetype_and_ext() + * in _wp_handle_upload(). Using wp_check_filetype() would be sufficient here. + */ $file_type = wp_check_filetype( $filename ); $mime_type = $file_type['type']; @@ -2550,27 +2552,40 @@ function wp_unique_filename( $dir, $filename, $unique_filename_callback = null ) $lc_ext = strtolower( $ext ); $_dir = trailingslashit( $dir ); - // If the extension is uppercase add an alternate file name with lowercase extension. Both need to be tested - // for uniqueness as the extension will be changed to lowercase for better compatibility with different filesystems. - // Fixes an inconsistency in WP < 2.9 where uppercase extensions were allowed but image sub-sizes were created with - // lowercase extensions. + /* + * If the extension is uppercase add an alternate file name with lowercase extension. + * Both need to be tested for uniqueness as the extension will be changed to lowercase + * for better compatibility with different filesystems. Fixes an inconsistency in WP < 2.9 + * where uppercase extensions were allowed but image sub-sizes were created with + * lowercase extensions. + */ if ( $ext && $lc_ext !== $ext ) { $lc_filename = preg_replace( '|' . preg_quote( $ext ) . '$|', $lc_ext, $filename ); } - // Increment the number added to the file name if there are any files in $dir whose names match one of the - // possible name variations. + /* + * Increment the number added to the file name if there are any files in $dir + * whose names match one of the possible name variations. + */ while ( file_exists( $_dir . $filename ) || ( $lc_filename && file_exists( $_dir . $lc_filename ) ) ) { $new_number = (int) $number + 1; if ( $lc_filename ) { - $lc_filename = str_replace( array( "-{$number}{$lc_ext}", "{$number}{$lc_ext}" ), "-{$new_number}{$lc_ext}", $lc_filename ); + $lc_filename = str_replace( + array( "-{$number}{$lc_ext}", "{$number}{$lc_ext}" ), + "-{$new_number}{$lc_ext}", + $lc_filename + ); } if ( '' === "{$number}{$ext}" ) { $filename = "{$filename}-{$new_number}"; } else { - $filename = str_replace( array( "-{$number}{$ext}", "{$number}{$ext}" ), "-{$new_number}{$ext}", $filename ); + $filename = str_replace( + array( "-{$number}{$ext}", "{$number}{$ext}" ), + "-{$new_number}{$ext}", + $filename + ); } $number = $new_number; @@ -2581,8 +2596,10 @@ function wp_unique_filename( $dir, $filename, $unique_filename_callback = null ) $filename = $lc_filename; } - // Prevent collisions with existing file names that contain dimension-like strings - // (whether they are subsizes or originals uploaded prior to #42437). + /* + * Prevent collisions with existing file names that contain dimension-like strings + * (whether they are subsizes or originals uploaded prior to #42437). + */ $files = array(); $count = 10000; @@ -2617,15 +2634,21 @@ function wp_unique_filename( $dir, $filename, $unique_filename_callback = null ) if ( ! empty( $files ) ) { $count = count( $files ); - // Ensure this never goes into infinite loop - // as it uses pathinfo() and regex in the check, but string replacement for the changes. + /* + * Ensure this never goes into infinite loop as it uses pathinfo() and regex in the check, + * but string replacement for the changes. + */ $i = 0; while ( $i <= $count && _wp_check_existing_file_names( $filename, $files ) ) { $new_number = (int) $number + 1; // If $ext is uppercase it was replaced with the lowercase version after the previous loop. - $filename = str_replace( array( "-{$number}{$lc_ext}", "{$number}{$lc_ext}" ), "-{$new_number}{$lc_ext}", $filename ); + $filename = str_replace( + array( "-{$number}{$lc_ext}", "{$number}{$lc_ext}" ), + "-{$new_number}{$lc_ext}", + $filename + ); $number = $new_number; $i++; @@ -2633,8 +2656,10 @@ function wp_unique_filename( $dir, $filename, $unique_filename_callback = null ) } } - // Check if an image will be converted after uploading or some existing images sub-sizes file names may conflict - // when regenerated. If yes, ensure the new file name will be unique and will produce unique sub-sizes. + /* + * Check if an image will be converted after uploading or some existing image sub-size file names may conflict + * when regenerated. If yes, ensure the new file name will be unique and will produce unique sub-sizes. + */ if ( $is_image ) { /** This filter is documented in wp-includes/class-wp-image-editor.php */ $output_formats = apply_filters( 'image_editor_output_format', array(), $_dir . $filename, $mime_type ); @@ -2668,8 +2693,10 @@ function wp_unique_filename( $dir, $filename, $unique_filename_callback = null ) } if ( ! empty( $alt_filenames ) ) { - // Add the original filename. It needs to be checked again together with the alternate filenames - // when $number is incremented. + /* + * Add the original filename. It needs to be checked again + * together with the alternate filenames when $number is incremented. + */ $alt_filenames[ $lc_ext ] = $filename; // Ensure no infinite loop. @@ -2679,12 +2706,22 @@ function wp_unique_filename( $dir, $filename, $unique_filename_callback = null ) $new_number = (int) $number + 1; foreach ( $alt_filenames as $alt_ext => $alt_filename ) { - $alt_filenames[ $alt_ext ] = str_replace( array( "-{$number}{$alt_ext}", "{$number}{$alt_ext}" ), "-{$new_number}{$alt_ext}", $alt_filename ); + $alt_filenames[ $alt_ext ] = str_replace( + array( "-{$number}{$alt_ext}", "{$number}{$alt_ext}" ), + "-{$new_number}{$alt_ext}", + $alt_filename + ); } - // Also update the $number in (the output) $filename. - // If the extension was uppercase it was already replaced with the lowercase version. - $filename = str_replace( array( "-{$number}{$lc_ext}", "{$number}{$lc_ext}" ), "-{$new_number}{$lc_ext}", $filename ); + /* + * Also update the $number in (the output) $filename. + * If the extension was uppercase it was already replaced with the lowercase version. + */ + $filename = str_replace( + array( "-{$number}{$lc_ext}", "{$number}{$lc_ext}" ), + "-{$new_number}{$lc_ext}", + $filename + ); $number = $new_number; $i++; diff --git a/wp-includes/load.php b/wp-includes/load.php index 60ce480656..560c6d016c 100644 --- a/wp-includes/load.php +++ b/wp-includes/load.php @@ -426,7 +426,7 @@ function wp_debug_mode() { * Filters whether to allow the debug mode check to occur. * * This filter runs before it can be used by plugins. It is designed for - * non-web run-times. Returning false causes the `WP_DEBUG` and related + * non-web runtimes. Returning false causes the `WP_DEBUG` and related * constants to not be checked and the default PHP values for errors * will be used unless you take care to update them yourself. * @@ -673,7 +673,7 @@ function wp_start_object_cache() { * Filters whether to enable loading of the object-cache.php drop-in. * * This filter runs before it can be used by plugins. It is designed for non-web - * run-times. If false is returned, object-cache.php will never be loaded. + * runtimes. If false is returned, object-cache.php will never be loaded. * * @since 5.8.0 * diff --git a/wp-includes/template-canvas.php b/wp-includes/template-canvas.php index 2972c94bd1..55f03267c8 100644 --- a/wp-includes/template-canvas.php +++ b/wp-includes/template-canvas.php @@ -5,7 +5,7 @@ * @package WordPress */ -/** +/* * Get the template HTML. * This needs to run before so that blocks can add scripts and styles in wp_head(). */ diff --git a/wp-includes/user.php b/wp-includes/user.php index 8fad744dad..3604d94389 100644 --- a/wp-includes/user.php +++ b/wp-includes/user.php @@ -2158,7 +2158,7 @@ function wp_insert_user( $userdata ) { * It only includes data in the users table, not any user metadata. * * @since 4.9.0 - * @since 5.8.0 The $userdata parameter was added. + * @since 5.8.0 The `$userdata` parameter was added. * * @param array $data { * Values and keys for the user. @@ -2203,7 +2203,7 @@ function wp_insert_user( $userdata ) { * For custom meta fields, see the {@see 'insert_custom_user_meta'} filter. * * @since 4.4.0 - * @since 5.8.0 The $userdata parameter was added. + * @since 5.8.0 The `$userdata` parameter was added. * * @param array $meta { * Default meta values and keys for the user. @@ -2274,7 +2274,7 @@ function wp_insert_user( $userdata ) { * Fires immediately after an existing user is updated. * * @since 2.0.0 - * @since 5.8.0 The $userdata parameter was added. + * @since 5.8.0 The `$userdata` parameter was added. * * @param int $user_id User ID. * @param WP_User $old_user_data Object containing user's data prior to update. @@ -2308,7 +2308,7 @@ function wp_insert_user( $userdata ) { * Fires immediately after a new user is registered. * * @since 1.5.0 - * @since 5.8.0 The $userdata parameter was added. + * @since 5.8.0 The `$userdata` parameter was added. * * @param int $user_id User ID. * @param array $userdata The raw array of data passed to wp_insert_user(). diff --git a/wp-includes/version.php b/wp-includes/version.php index 82372c463f..bd58b8d279 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -16,7 +16,7 @@ * * @global string $wp_version */ -$wp_version = '5.9-beta2-52351'; +$wp_version = '5.9-beta2-52352'; /** * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.