From 6263f22b10fae3010d8a0c282f305f5ffebceda6 Mon Sep 17 00:00:00 2001 From: audrasjb Date: Mon, 10 Jul 2023 22:48: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]. Props costdev, audrasjb. See #58459. Built from https://develop.svn.wordpress.org/trunk@56192 git-svn-id: http://core.svn.wordpress.org/trunk@55704 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-includes/ms-default-constants.php | 6 ++- wp-includes/ms-functions.php | 18 ++++--- wp-includes/ms-load.php | 12 +++-- wp-includes/ms-site.php | 6 ++- wp-includes/nav-menu.php | 6 ++- wp-includes/option.php | 18 ++++--- wp-includes/pluggable.php | 72 ++++++++++++++++++---------- wp-includes/post-template.php | 6 ++- wp-includes/post.php | 6 ++- wp-includes/query.php | 6 ++- wp-includes/rest-api.php | 42 ++++++++++------ wp-includes/revision.php | 18 ++++--- wp-includes/version.php | 2 +- 13 files changed, 145 insertions(+), 73 deletions(-) diff --git a/wp-includes/ms-default-constants.php b/wp-includes/ms-default-constants.php index 128b47b9ae..99d6461f62 100644 --- a/wp-includes/ms-default-constants.php +++ b/wp-includes/ms-default-constants.php @@ -28,8 +28,10 @@ function ms_upload_constants() { define( 'UPLOADBLOGSDIR', 'wp-content/blogs.dir' ); } - // Note, the main site in a post-MU network uses wp-content/uploads. - // This is handled in wp_upload_dir() by ignoring UPLOADS for this case. + /* + * Note, the main site in a post-MU network uses wp-content/uploads. + * This is handled in wp_upload_dir() by ignoring UPLOADS for this case. + */ if ( ! defined( 'UPLOADS' ) ) { $site_id = get_current_blog_id(); diff --git a/wp-includes/ms-functions.php b/wp-includes/ms-functions.php index 3a4dd3115d..09ee2a5c53 100644 --- a/wp-includes/ms-functions.php +++ b/wp-includes/ms-functions.php @@ -245,8 +245,10 @@ function remove_user_from_blog( $user_id, $blog_id = 0, $reassign = 0 ) { */ do_action( 'remove_user_from_blog', $user_id, $blog_id, $reassign ); - // If being removed from the primary blog, set a new primary - // if the user is assigned to multiple blogs. + /* + * If being removed from the primary blog, set a new primary + * if the user is assigned to multiple blogs. + */ $primary_blog = get_user_meta( $user_id, 'primary_blog', true ); if ( $primary_blog == $blog_id ) { $new_id = ''; @@ -717,8 +719,10 @@ function wpmu_validate_blog_signup( $blogname, $blog_title, $user = '' ) { } } - // Has someone already signed up for this domain? - // TODO: Check email too? + /* + * Has someone already signed up for this domain? + * TODO: Check email too? + */ $signup = $wpdb->get_row( $wpdb->prepare( "SELECT * FROM $wpdb->signups WHERE domain = %s AND path = %s", $mydomain, $path ) ); if ( $signup instanceof stdClass ) { $diff = time() - mysql2date( 'U', $signup->registered ); @@ -1939,8 +1943,10 @@ function get_most_recent_post_of_user( $user_id ) { $user_blogs = get_blogs_of_user( (int) $user_id ); $most_recent_post = array(); - // Walk through each blog and get the most recent post - // published by $user_id. + /* + * Walk through each blog and get the most recent post + * published by $user_id. + */ foreach ( (array) $user_blogs as $blog ) { $prefix = $wpdb->get_blog_prefix( $blog->userblog_id ); $recent_post = $wpdb->get_row( $wpdb->prepare( "SELECT ID, post_date_gmt FROM {$prefix}posts WHERE post_author = %d AND post_type = 'post' AND post_status = 'publish' ORDER BY post_date_gmt DESC LIMIT 1", $user_id ), ARRAY_A ); diff --git a/wp-includes/ms-load.php b/wp-includes/ms-load.php index 7601a6a279..afac9b1147 100644 --- a/wp-includes/ms-load.php +++ b/wp-includes/ms-load.php @@ -226,8 +226,10 @@ function get_site_by_path( $domain, $path, $segments = null ) { * then cache whether we can just always ignore paths. */ - // Either www or non-www is supported, not both. If a www domain is requested, - // query for both to provide the proper redirect. + /* + * Either www or non-www is supported, not both. If a www domain is requested, + * query for both to provide the proper redirect. + */ $domains = array( $domain ); if ( str_starts_with( $domain, 'www.' ) ) { $domains[] = substr( $domain, 4 ); @@ -310,8 +312,10 @@ function ms_load_current_site_and_network( $domain, $path, $subdomain = false ) if ( 0 === strcasecmp( $current_site->domain, $domain ) && 0 === strcasecmp( $current_site->path, $path ) ) { $current_blog = get_site_by_path( $domain, $path ); } elseif ( '/' !== $current_site->path && 0 === strcasecmp( $current_site->domain, $domain ) && 0 === stripos( $path, $current_site->path ) ) { - // If the current network has a path and also matches the domain and path of the request, - // we need to look for a site using the first path segment following the network's path. + /* + * If the current network has a path and also matches the domain and path of the request, + * we need to look for a site using the first path segment following the network's path. + */ $current_blog = get_site_by_path( $domain, $path, 1 + count( explode( '/', trim( $current_site->path, '/' ) ) ) ); } else { // Otherwise, use the first path segment (as usual). diff --git a/wp-includes/ms-site.php b/wp-includes/ms-site.php index 486fad2414..256932be65 100644 --- a/wp-includes/ms-site.php +++ b/wp-includes/ms-site.php @@ -114,8 +114,10 @@ function wp_insert_site( array $data ) { $meta['WPLANG'] = get_network_option( $new_site->network_id, 'WPLANG' ); } - // Rebuild the data expected by the `wpmu_new_blog` hook prior to 5.1.0 using allowed keys. - // The `$allowed_data_fields` matches the one used in `wpmu_create_blog()`. + /* + * Rebuild the data expected by the `wpmu_new_blog` hook prior to 5.1.0 using allowed keys. + * The `$allowed_data_fields` matches the one used in `wpmu_create_blog()`. + */ $allowed_data_fields = array( 'public', 'archived', 'mature', 'spam', 'deleted', 'lang_id' ); $meta = array_merge( array_intersect_key( $data, array_flip( $allowed_data_fields ) ), $meta ); diff --git a/wp-includes/nav-menu.php b/wp-includes/nav-menu.php index 29ee71391f..b43e45601c 100644 --- a/wp-includes/nav-menu.php +++ b/wp-includes/nav-menu.php @@ -547,8 +547,10 @@ function wp_update_nav_menu_item( $menu_id = 0, $menu_item_db_id = 0, $menu_item do_action( 'wp_add_nav_menu_item', $menu_id, $menu_item_db_id, $args ); } - // Associate the menu item with the menu term. - // Only set the menu term if it isn't set to avoid unnecessary wp_get_object_terms(). + /* + * Associate the menu item with the menu term. + * Only set the menu term if it isn't set to avoid unnecessary wp_get_object_terms(). + */ if ( $menu_id && ( ! $update || ! is_object_in_term( $menu_item_db_id, 'nav_menu', (int) $menu->term_id ) ) ) { $update_terms = wp_set_object_terms( $menu_item_db_id, array( $menu->term_id ), 'nav_menu' ); if ( is_wp_error( $update_terms ) ) { diff --git a/wp-includes/option.php b/wp-includes/option.php index 48e8676ed2..5d7cbc0b15 100644 --- a/wp-includes/option.php +++ b/wp-includes/option.php @@ -664,8 +664,10 @@ function add_option( $option, $value = '', $deprecated = '', $autoload = 'yes' ) $value = sanitize_option( $option, $value ); - // Make sure the option doesn't already exist. - // We can check the 'notoptions' cache before we ask for a DB query. + /* + * Make sure the option doesn't already exist. + * We can check the 'notoptions' cache before we ask for a DB query. + */ $notoptions = wp_cache_get( 'notoptions', 'options' ); if ( ! is_array( $notoptions ) || ! isset( $notoptions[ $option ] ) ) { @@ -998,8 +1000,10 @@ function set_transient( $transient, $value, $expiration = 0 ) { } $result = add_option( $transient_option, $value, '', $autoload ); } else { - // If expiration is requested, but the transient has no timeout option, - // delete, then re-create transient rather than update. + /* + * If expiration is requested, but the transient has no timeout option, + * delete, then re-create transient rather than update. + */ $update = true; if ( $expiration ) { @@ -1598,8 +1602,10 @@ function add_network_option( $network_id, $option, $value ) { } else { $cache_key = "$network_id:$option"; - // Make sure the option doesn't already exist. - // We can check the 'notoptions' cache before we ask for a DB query. + /* + * Make sure the option doesn't already exist. + * We can check the 'notoptions' cache before we ask for a DB query. + */ $notoptions = wp_cache_get( $notoptions_key, 'site-options' ); if ( ! is_array( $notoptions ) || ! isset( $notoptions[ $option ] ) ) { diff --git a/wp-includes/pluggable.php b/wp-includes/pluggable.php index 45ee504fda..cd3cad1b7b 100644 --- a/wp-includes/pluggable.php +++ b/wp-includes/pluggable.php @@ -267,8 +267,10 @@ if ( ! function_exists( 'wp_mail' ) ) : $headers = array(); } else { if ( ! is_array( $headers ) ) { - // Explode the headers out, so this function can take - // both string headers and an array of headers. + /* + * Explode the headers out, so this function can take + * both string headers and an array of headers. + */ $tempheaders = explode( "\n", str_replace( "\r\n", "\n", $headers ) ); } else { $tempheaders = $headers; @@ -616,8 +618,10 @@ if ( ! function_exists( 'wp_authenticate' ) ) : $user = apply_filters( 'authenticate', null, $username, $password ); if ( null == $user ) { - // TODO: What should the error message be? (Or would these even happen?) - // Only needed if all authentication handlers fail to return anything. + /* + * TODO: What should the error message be? (Or would these even happen?) + * Only needed if all authentication handlers fail to return anything. + */ $user = new WP_Error( 'authentication_failed', __( 'Error: Invalid username, email address or incorrect password.' ) ); } @@ -1561,8 +1565,10 @@ if ( ! function_exists( 'wp_validate_redirect' ) ) : $location = 'http:' . $location; } - // In PHP 5 parse_url() may fail if the URL query part contains 'http://'. - // See https://bugs.php.net/bug.php?id=38143 + /* + * In PHP 5 parse_url() may fail if the URL query part contains 'http://'. + * See https://bugs.php.net/bug.php?id=38143 + */ $cut = strpos( $location, '?' ); $test = $cut ? substr( $location, 0, $cut ) : $location; @@ -1587,8 +1593,10 @@ if ( ! function_exists( 'wp_validate_redirect' ) ) : $location = '/' . ltrim( $path . '/', '/' ) . $location; } - // Reject if certain components are set but host is not. - // This catches URLs like https:host.com for which parse_url() does not set the host field. + /* + * Reject if certain components are set but host is not. + * This catches URLs like https:host.com for which parse_url() does not set the host field. + */ if ( ! isset( $lp['host'] ) && ( isset( $lp['scheme'] ) || isset( $lp['user'] ) || isset( $lp['pass'] ) || isset( $lp['port'] ) ) ) { return $fallback_url; } @@ -1714,8 +1722,10 @@ if ( ! function_exists( 'wp_notify_postauthor' ) ) : $comment_author_domain = gethostbyaddr( $comment->comment_author_IP ); } - // The blogname option is escaped with esc_html() on the way into the database in sanitize_option(). - // We want to reverse this for the plain text arena of emails. + /* + * The blogname option is escaped with esc_html() on the way into the database in sanitize_option(). + * We want to reverse this for the plain text arena of emails. + */ $blogname = wp_specialchars_decode( get_option( 'blogname' ), ENT_QUOTES ); $comment_content = wp_specialchars_decode( $comment->comment_content ); @@ -1903,8 +1913,10 @@ if ( ! function_exists( 'wp_notify_moderator' ) ) : $comments_waiting = $wpdb->get_var( "SELECT COUNT(*) FROM $wpdb->comments WHERE comment_approved = '0'" ); - // The blogname option is escaped with esc_html() on the way into the database in sanitize_option(). - // We want to reverse this for the plain text arena of emails. + /* + * The blogname option is escaped with esc_html() on the way into the database in sanitize_option(). + * We want to reverse this for the plain text arena of emails. + */ $blogname = wp_specialchars_decode( get_option( 'blogname' ), ENT_QUOTES ); $comment_content = wp_specialchars_decode( $comment->comment_content ); @@ -2042,13 +2054,17 @@ if ( ! function_exists( 'wp_password_change_notification' ) ) : * @param WP_User $user User object. */ function wp_password_change_notification( $user ) { - // Send a copy of password change notification to the admin, - // but check to see if it's the admin whose password we're changing, and skip this. + /* + * Send a copy of password change notification to the admin, + * but check to see if it's the admin whose password we're changing, and skip this. + */ if ( 0 !== strcasecmp( $user->user_email, get_option( 'admin_email' ) ) ) { /* translators: %s: User name. */ $message = sprintf( __( 'Password changed for user: %s' ), $user->user_login ) . "\r\n"; - // The blogname option is escaped with esc_html() on the way into the database in sanitize_option(). - // We want to reverse this for the plain text arena of emails. + /* + * The blogname option is escaped with esc_html() on the way into the database in sanitize_option(). + * We want to reverse this for the plain text arena of emails. + */ $blogname = wp_specialchars_decode( get_option( 'blogname' ), ENT_QUOTES ); $wp_password_change_notification_email = array( @@ -2115,8 +2131,10 @@ if ( ! function_exists( 'wp_new_user_notification' ) ) : $user = get_userdata( $user_id ); - // The blogname option is escaped with esc_html() on the way into the database in sanitize_option(). - // We want to reverse this for the plain text arena of emails. + /* + * The blogname option is escaped with esc_html() on the way into the database in sanitize_option(). + * We want to reverse this for the plain text arena of emails. + */ $blogname = wp_specialchars_decode( get_option( 'blogname' ), ENT_QUOTES ); /** @@ -2572,8 +2590,10 @@ if ( ! function_exists( 'wp_check_password' ) ) : return apply_filters( 'check_password', $check, $password, $hash, $user_id ); } - // If the stored hash is longer than an MD5, - // presume the new style phpass portable hash. + /* + * If the stored hash is longer than an MD5, + * presume the new style phpass portable hash. + */ if ( empty( $wp_hasher ) ) { require_once ABSPATH . WPINC . '/class-phpass.php'; // By default, use the portable hash from phpass. @@ -2651,8 +2671,10 @@ if ( ! function_exists( 'wp_rand' ) ) : function wp_rand( $min = null, $max = null ) { global $rnd_value; - // Some misconfigured 32-bit environments (Entropy PHP, for example) - // truncate integers larger than PHP_INT_MAX to PHP_INT_MAX rather than overflowing them to floats. + /* + * Some misconfigured 32-bit environments (Entropy PHP, for example) + * truncate integers larger than PHP_INT_MAX to PHP_INT_MAX rather than overflowing them to floats. + */ $max_random_number = 3000000000 === 2147483647 ? (float) '4294967295' : 4294967295; // 4294967295 = 0xffffffff if ( null === $min ) { @@ -2687,8 +2709,10 @@ if ( ! function_exists( 'wp_rand' ) ) : } } - // Reset $rnd_value after 14 uses. - // 32 (md5) + 40 (sha1) + 40 (sha1) / 8 = 14 random numbers from $rnd_value. + /* + * Reset $rnd_value after 14 uses. + * 32 (md5) + 40 (sha1) + 40 (sha1) / 8 = 14 random numbers from $rnd_value. + */ if ( strlen( $rnd_value ) < 8 ) { if ( defined( 'WP_SETUP_CONFIG' ) ) { static $seed = ''; diff --git a/wp-includes/post-template.php b/wp-includes/post-template.php index f6bca3ed8b..ceedfa4806 100644 --- a/wp-includes/post-template.php +++ b/wp-includes/post-template.php @@ -285,8 +285,10 @@ function get_the_content( $more_link_text = null, $strip_teaser = false, $post = return ''; } - // Use the globals if the $post parameter was not specified, - // but only after they have been set up in setup_postdata(). + /* + * Use the globals if the $post parameter was not specified, + * but only after they have been set up in setup_postdata(). + */ if ( null === $post && did_action( 'the_post' ) ) { $elements = compact( 'page', 'more', 'preview', 'pages', 'multipage' ); } else { diff --git a/wp-includes/post.php b/wp-includes/post.php index 3716fceef0..6675a57013 100644 --- a/wp-includes/post.php +++ b/wp-includes/post.php @@ -6614,8 +6614,10 @@ function wp_get_attachment_caption( $post_id = 0 ) { function wp_get_attachment_thumb_url( $post_id = 0 ) { $post_id = (int) $post_id; - // This uses image_downsize() which also looks for the (very) old format $image_meta['thumb'] - // when the newer format $image_meta['sizes']['thumbnail'] doesn't exist. + /* + * This uses image_downsize() which also looks for the (very) old format $image_meta['thumb'] + * when the newer format $image_meta['sizes']['thumbnail'] doesn't exist. + */ $thumbnail_url = wp_get_attachment_image_url( $post_id, 'thumbnail' ); if ( empty( $thumbnail_url ) ) { diff --git a/wp-includes/query.php b/wp-includes/query.php index 90791d86ca..c92257ee0d 100644 --- a/wp-includes/query.php +++ b/wp-includes/query.php @@ -1139,8 +1139,10 @@ function _find_post_by_old_slug( $post_type ) { $query = $wpdb->prepare( "SELECT post_id FROM $wpdb->postmeta, $wpdb->posts WHERE ID = post_id AND post_type = %s AND meta_key = '_wp_old_slug' AND meta_value = %s", $post_type, get_query_var( 'name' ) ); - // If year, monthnum, or day have been specified, make our query more precise - // just in case there are multiple identical _wp_old_slug values. + /* + * If year, monthnum, or day have been specified, make our query more precise + * just in case there are multiple identical _wp_old_slug values. + */ if ( get_query_var( 'year' ) ) { $query .= $wpdb->prepare( ' AND YEAR(post_date) = %d', get_query_var( 'year' ) ); } diff --git a/wp-includes/rest-api.php b/wp-includes/rest-api.php index 22697fab4d..a8a2aac177 100644 --- a/wp-includes/rest-api.php +++ b/wp-includes/rest-api.php @@ -473,8 +473,10 @@ function get_rest_url( $blog_id = null, $path = '/', $scheme = 'rest' ) { $url .= $path; } else { $url = trailingslashit( get_home_url( $blog_id, '', $scheme ) ); - // nginx only allows HTTP/1.0 methods when redirecting from / to /index.php. - // To work around this, we manually add index.php to the URL, avoiding the redirect. + /* + * nginx only allows HTTP/1.0 methods when redirecting from / to /index.php. + * To work around this, we manually add index.php to the URL, avoiding the redirect. + */ if ( ! str_ends_with( $url, 'index.php' ) ) { $url .= 'index.php'; } @@ -632,8 +634,10 @@ function rest_ensure_response( $response ) { return $response; } - // While WP_HTTP_Response is the base class of WP_REST_Response, it doesn't provide - // all the required methods used in WP_REST_Server::dispatch(). + /* + * While WP_HTTP_Response is the base class of WP_REST_Response, it doesn't provide + * all the required methods used in WP_REST_Server::dispatch(). + */ if ( $response instanceof WP_HTTP_Response ) { return new WP_REST_Response( $response->get_data(), @@ -945,13 +949,17 @@ function rest_is_field_included( $field, $fields ) { } foreach ( $fields as $accepted_field ) { - // Check to see if $field is the parent of any item in $fields. - // A field "parent" should be accepted if "parent.child" is accepted. + /* + * Check to see if $field is the parent of any item in $fields. + * A field "parent" should be accepted if "parent.child" is accepted. + */ if ( str_starts_with( $accepted_field, "$field." ) ) { return true; } - // Conversely, if "parent" is accepted, all "parent.child" fields - // should also be accepted. + /* + * Conversely, if "parent" is accepted, all "parent.child" fields + * should also be accepted. + */ if ( str_starts_with( $field, "$accepted_field." ) ) { return true; } @@ -1609,8 +1617,10 @@ function rest_get_best_type_for_value( $value, $types ) { 'null' => 'is_null', ); - // Both arrays and objects allow empty strings to be converted to their types. - // But the best answer for this type is a string. + /* + * Both arrays and objects allow empty strings to be converted to their types. + * But the best answer for this type is a string. + */ if ( '' === $value && in_array( 'string', $types, true ) ) { return 'string'; } @@ -2191,8 +2201,10 @@ function rest_validate_value_from_schema( $value, $args, $param = '' ) { } } - // The "format" keyword should only be applied to strings. However, for backward compatibility, - // we allow the "format" keyword if the type keyword was not specified, or was set to an invalid value. + /* + * The "format" keyword should only be applied to strings. However, for backward compatibility, + * we allow the "format" keyword if the type keyword was not specified, or was set to an invalid value. + */ if ( isset( $args['format'] ) && ( ! isset( $args['type'] ) || 'string' === $args['type'] || ! in_array( $args['type'], $allowed_types, true ) ) ) { @@ -2858,8 +2870,10 @@ function rest_sanitize_value_from_schema( $value, $args, $param = '' ) { * @return array Modified reduce accumulator. */ function rest_preload_api_request( $memo, $path ) { - // array_reduce() doesn't support passing an array in PHP 5.2, - // so we need to make sure we start with one. + /* + * array_reduce() doesn't support passing an array in PHP 5.2, + * so we need to make sure we start with one. + */ if ( ! is_array( $memo ) ) { $memo = array(); } diff --git a/wp-includes/revision.php b/wp-includes/revision.php index 901f489ac4..e8bbcdbce4 100644 --- a/wp-includes/revision.php +++ b/wp-includes/revision.php @@ -190,8 +190,10 @@ function wp_save_post_revision( $post_id ) { $return = _wp_put_post_revision( $post ); - // If a limit for the number of revisions to keep has been set, - // delete the oldest ones. + /* + * If a limit for the number of revisions to keep has been set, + * delete the oldest ones. + */ $revisions_to_keep = wp_revisions_to_keep( $post ); if ( $revisions_to_keep < 0 ) { @@ -869,8 +871,10 @@ function _wp_upgrade_revisions_of_post( $post, $revisions ) { $locked = get_option( $lock ); if ( ! $locked ) { - // Can't write to the lock, and can't read the lock. - // Something broken has happened. + /* + * Can't write to the lock, and can't read the lock. + * Something broken has happened. + */ return false; } @@ -899,8 +903,10 @@ function _wp_upgrade_revisions_of_post( $post, $revisions ) { continue; } - // 1 is the latest revision version, so we're already up to date. - // No need to add a copy of the post as latest revision. + /* + * 1 is the latest revision version, so we're already up to date. + * No need to add a copy of the post as latest revision. + */ if ( 0 < $this_revision_version ) { $add_last = false; continue; diff --git a/wp-includes/version.php b/wp-includes/version.php index 0f773eba6b..a9f8788843 100644 --- a/wp-includes/version.php +++ b/wp-includes/version.php @@ -16,7 +16,7 @@ * * @global string $wp_version */ -$wp_version = '6.3-beta3-56191'; +$wp_version = '6.3-beta3-56192'; /** * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.