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
This commit is contained in:
audrasjb 2023-07-10 22:48:22 +00:00
parent 321158f726
commit 6263f22b10
13 changed files with 145 additions and 73 deletions

View File

@ -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();

View File

@ -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 );

View File

@ -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).

View File

@ -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 );

View File

@ -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 ) ) {

View File

@ -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 ] ) ) {

View File

@ -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', __( '<strong>Error:</strong> 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 = '';

View File

@ -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 {

View File

@ -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 ) ) {

View File

@ -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' ) );
}

View File

@ -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();
}

View File

@ -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;

View File

@ -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.