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

Props costdev, audrasjb.
See #58459.



Built from https://develop.svn.wordpress.org/trunk@56180


git-svn-id: http://core.svn.wordpress.org/trunk@55692 1a063a9b-81f0-0310-95a4-ce76da25c4cd

wp-includes/class-wp-theme.php

@@ -321,8 +321,10 @@ final class WP_Theme implements ArrayAccess {
 			return;
 		} else {
 			$this->headers = get_file_data( $this->theme_root . '/' . $theme_file, self::$file_headers, 'theme' );
-			// Default themes always trump their pretenders.
+			/*
-			// Properly identify default themes that are inside a directory within wp-content/themes.
+			 * Default themes always trump their pretenders.
+			 * Properly identify default themes that are inside a directory within wp-content/themes.
+			 */
 			$default_theme_slug = array_search( $this->headers['Name'], self::$default_themes, true );
 			if ( $default_theme_slug ) {
 				if ( basename( $this->stylesheet ) != $default_theme_slug ) {
@@ -389,16 +391,20 @@ final class WP_Theme implements ArrayAccess {
 
 		// If we got our data from cache, we can assume that 'template' is pointing to the right place.
 		if ( ! is_array( $cache ) && $this->template != $this->stylesheet && ! file_exists( $this->theme_root . '/' . $this->template . '/index.php' ) ) {
-			// If we're in a directory of themes inside /themes, look for the parent nearby.
+			/*
-			// wp-content/themes/directory-of-themes/*
+			 * If we're in a directory of themes inside /themes, look for the parent nearby.
+			 * wp-content/themes/directory-of-themes/*
+			 */
 			$parent_dir  = dirname( $this->stylesheet );
 			$directories = search_theme_directories();
 
 			if ( '.' !== $parent_dir && file_exists( $this->theme_root . '/' . $parent_dir . '/' . $this->template . '/index.php' ) ) {
 				$this->template = $parent_dir . '/' . $this->template;
 			} elseif ( $directories && isset( $directories[ $this->template ] ) ) {
-				// Look for the template in the search_theme_directories() results, in case it is in another theme root.
+				/*
-				// We don't look into directories of themes, just the theme root.
+				 * Look for the template in the search_theme_directories() results, in case it is in another theme root.
+				 * We don't look into directories of themes, just the theme root.
+				 */
 				$theme_root_template = $directories[ $this->template ]['theme_root'];
 			} else {
 				// Parent theme is missing.
@@ -1665,8 +1671,10 @@ final class WP_Theme implements ArrayAccess {
 			restore_current_blog();
 		}
 
-		// This is all super old MU back compat joy.
+		/*
-		// 'allowedthemes' keys things by stylesheet. 'allowed_themes' keyed things by name.
+		 * This is all super old MU back compat joy.
+		 * 'allowedthemes' keys things by stylesheet. 'allowed_themes' keyed things by name.
+		 */
 		if ( false === $allowed_themes[ $blog_id ] ) {
 			if ( $current ) {
 				$allowed_themes[ $blog_id ] = get_option( 'allowed_themes' );

wp-includes/class-wp-user.php

@@ -199,8 +199,7 @@ class WP_User {
 		}
 
 		if ( 'id' === $field ) {
-			// Make sure the value is numeric to avoid casting objects, for example,
+			// Make sure the value is numeric to avoid casting objects, for example, to int 1.
-			// to int 1.
 			if ( ! is_numeric( $value ) ) {
 				return false;
 			}

wp-includes/class-wp-xmlrpc-server.php

@@ -137,8 +137,10 @@ class wp_xmlrpc_server extends IXR_Server {
 			'metaWeblog.getCategories'         => 'this:mw_getCategories',
 			'metaWeblog.newMediaObject'        => 'this:mw_newMediaObject',
 
-			// MetaWeblog API aliases for Blogger API.
+			/*
-			// See http://www.xmlrpc.com/stories/storyReader$2460
+			 * MetaWeblog API aliases for Blogger API.
+			 * See http://www.xmlrpc.com/stories/storyReader$2460
+			 */
 			'metaWeblog.deletePost'            => 'this:blogger_deletePost',
 			'metaWeblog.getUsersBlogs'         => 'this:blogger_getUsersBlogs',
 
@@ -3121,8 +3123,10 @@ class wp_xmlrpc_server extends IXR_Server {
 		/** This action is documented in wp-includes/class-wp-xmlrpc-server.php */
 		do_action( 'xmlrpc_call', 'wp.deletePage', $args, $this );
 
-		// Get the current page based on the 'page_id' and
+		/*
-		// make sure it is a page and not a post.
+		 * Get the current page based on the 'page_id' and
+		 * make sure it is a page and not a post.
+		 */
 		$actual_page = get_post( $page_id, ARRAY_A );
 		if ( ! $actual_page || ( 'page' !== $actual_page['post_type'] ) ) {
 			return new IXR_Error( 404, __( 'Sorry, no such page.' ) );
@@ -3411,14 +3415,18 @@ class wp_xmlrpc_server extends IXR_Server {
 			return new IXR_Error( 401, __( 'Sorry, you are not allowed to add a category.' ) );
 		}
 
-		// If no slug was provided, make it empty
+		/*
-		// so that WordPress will generate one.
+		 * If no slug was provided, make it empty
+		 * so that WordPress will generate one.
+		 */
 		if ( empty( $category['slug'] ) ) {
 			$category['slug'] = '';
 		}
 
-		// If no parent_id was provided, make it empty
+		/*
-		// so that it will be a top-level page (no parent).
+		 * If no parent_id was provided, make it empty
+		 * so that it will be a top-level page (no parent).
+		 */
 		if ( ! isset( $category['parent_id'] ) ) {
 			$category['parent_id'] = '';
 		}
@@ -5618,8 +5626,10 @@ class wp_xmlrpc_server extends IXR_Server {
 
 		$this->attach_uploads( $post_id, $post_content );
 
-		// Handle post formats if assigned, value is validated earlier
+		/*
-		// in this function.
+		 * Handle post formats if assigned, value is validated earlier
+		 * in this function.
+		 */
 		if ( isset( $content_struct['wp_post_format'] ) ) {
 			set_post_format( $post_id, $content_struct['wp_post_format'] );
 		}
@@ -6998,8 +7008,10 @@ class wp_xmlrpc_server extends IXR_Server {
 					continue;
 				}
 
-				// We're going to use this fake tag to mark the context in a bit.
+				/*
-				// The marker is needed in case the link text appears more than once in the paragraph.
+				 * We're going to use this fake tag to mark the context in a bit.
+				 * The marker is needed in case the link text appears more than once in the paragraph.
+				 */
 				$excerpt = preg_replace( '|\</?wpcontext\>|', '', $para );
 
 				// prevent really long link text

wp-includes/class-wp.php

@@ -200,8 +200,7 @@ class WP {
 				$self     = trim( $self, '/' );
 			}
 
-			// The requested permalink is in $pathinfo for path info requests and
+			// The requested permalink is in $pathinfo for path info requests and $req_uri for other requests.
-			// $req_uri for other requests.
 			if ( ! empty( $pathinfo ) && ! preg_match( '|^.*' . $wp_rewrite->index . '$|', $pathinfo ) ) {
 				$requested_path = $pathinfo;
 			} else {

wp-includes/class-wpdb.php

@@ -2155,8 +2155,10 @@ class wpdb {
 			$host   = substr( $host, 0, $socket_pos );
 		}
 
-		// We need to check for an IPv6 address first.
+		/*
-		// An IPv6 address will always contain at least two colons.
+		 * We need to check for an IPv6 address first.
+		 * An IPv6 address will always contain at least two colons.
+		 */
 		if ( substr_count( $host, ':' ) > 1 ) {
 			$pattern = '#^(?:\[)?(?P<host>[0-9a-fA-F:]+)(?:\]:(?P<port>[\d]+))?#';
 			$is_ipv6 = true;
@@ -2213,8 +2215,10 @@ class wpdb {
 		}
 
 		for ( $tries = 1; $tries <= $this->reconnect_retries; $tries++ ) {
-			// On the last try, re-enable warnings. We want to see a single instance
+			/*
-			// of the "unable to connect" message on the bail() screen, if it appears.
+			 * On the last try, re-enable warnings. We want to see a single instance
+			 * of the "unable to connect" message on the bail() screen, if it appears.
+			 */
 			if ( $this->reconnect_retries === $tries && WP_DEBUG ) {
 				error_reporting( $error_reporting );
 			}
@@ -2230,8 +2234,10 @@ class wpdb {
 			sleep( 1 );
 		}
 
-		// If template_redirect has already happened, it's too late for wp_die()/dead_db().
+		/*
-		// Let's just return and hope for the best.
+		 * If template_redirect has already happened, it's too late for wp_die()/dead_db().
+		 * Let's just return and hope for the best.
+		 */
 		if ( did_action( 'template_redirect' ) ) {
 			return false;
 		}
@@ -2264,8 +2270,10 @@ class wpdb {
 		// We weren't able to reconnect, so we better bail.
 		$this->bail( $message, 'db_connect_fail' );
 
-		// Call dead_db() if bail didn't die, because this database is no more.
+		/*
-		// It has ceased to be (at least temporarily).
+		 * Call dead_db() if bail didn't die, because this database is no more.
+		 * It has ceased to be (at least temporarily).
+		 */
 		dead_db();
 	}
 
@@ -2313,8 +2321,10 @@ class wpdb {
 		// If we're writing to the database, make sure the query will write safely.
 		if ( $this->check_current_query && ! $this->check_ascii( $query ) ) {
 			$stripped_query = $this->strip_invalid_text_from_query( $query );
-			// strip_invalid_text_from_query() can perform queries, so we need
+			/*
-			// to flush again, just to make sure everything is clear.
+			 * strip_invalid_text_from_query() can perform queries, so we need
+			 * to flush again, just to make sure everything is clear.
+			 */
 			$this->flush();
 			if ( $stripped_query !== $query ) {
 				$this->insert_id  = 0;
@@ -2342,8 +2352,10 @@ class wpdb {
 				if ( $this->dbh instanceof mysqli ) {
 					$mysql_errno = mysqli_errno( $this->dbh );
 				} else {
-					// $dbh is defined, but isn't a real connection.
+					/*
-					// Something has gone horribly wrong, let's try a reconnect.
+					 * $dbh is defined, but isn't a real connection.
+					 * Something has gone horribly wrong, let's try a reconnect.
+					 */
 					$mysql_errno = 2006;
 				}
 			} else {
@@ -3122,8 +3134,10 @@ class wpdb {
 			// Return an integer-keyed array of row objects.
 			return $this->last_result;
 		} elseif ( OBJECT_K === $output ) {
-			// Return an array of row objects with keys from column 1.
+			/*
-			// (Duplicates are discarded.)
+			 * Return an array of row objects with keys from column 1.
+			 * (Duplicates are discarded.)
+			 */
 			if ( $this->last_result ) {
 				foreach ( $this->last_result as $row ) {
 					$var_by_ref = get_object_vars( $row );
@@ -3529,8 +3543,10 @@ class wpdb {
 				$truncate_by_byte_length = 'byte' === $value['length']['type'];
 			} else {
 				$length = false;
-				// Since we have no length, we'll never truncate. Initialize the variable to false.
+				/*
-				// True would take us through an unnecessary (for this case) codepath below.
+				 * Since we have no length, we'll never truncate. Initialize the variable to false.
+				 * True would take us through an unnecessary (for this case) codepath below.
+				 */
 				$truncate_by_byte_length = false;
 			}
 

wp-includes/comment.php

@@ -651,8 +651,10 @@ function sanitize_comment_cookies() {
 function wp_allow_comment( $commentdata, $wp_error = false ) {
 	global $wpdb;
 
-	// Simple duplicate check.
+	/*
-	// expected_slashed ($comment_post_ID, $comment_author, $comment_author_email, $comment_content)
+	 * Simple duplicate check.
+	 * expected_slashed ($comment_post_ID, $comment_author, $comment_author_email, $comment_content)
+	 */
 	$dupe = $wpdb->prepare(
 		"SELECT comment_ID FROM $wpdb->comments WHERE comment_post_ID = %d AND comment_parent = %s AND comment_approved != 'trash' AND ( comment_author = %s ",
 		wp_unslash( $commentdata['comment_post_ID'] ),
@@ -1352,8 +1354,7 @@ function wp_check_comment_disallowed_list( $author, $email, $url, $comment, $use
 		if ( empty( $word ) ) {
 			continue; }
 
-		// Do some escaping magic so that '#' chars
+		// Do some escaping magic so that '#' chars in the spam words don't break things:
-		// in the spam words don't break things:
 		$word = preg_quote( $word, '#' );
 
 		$pattern = "#$word#iu";

wp-includes/cron.php

@@ -541,8 +541,10 @@ function wp_unschedule_event( $timestamp, $hook, $args = array(), $wp_error = fa
  *                            if unscheduling one or more events fail.
  */
 function wp_clear_scheduled_hook( $hook, $args = array(), $wp_error = false ) {
-	// Backward compatibility.
+	/*
-	// Previously, this function took the arguments as discrete vars rather than an array like the rest of the API.
+	 * Backward compatibility.
+	 * Previously, this function took the arguments as discrete vars rather than an array like the rest of the API.
+	 */
 	if ( ! is_array( $args ) ) {
 		_deprecated_argument( __FUNCTION__, '3.0.0', __( 'This argument has changed to an array to match the behavior of the other cron functions.' ) );
 		$args     = array_slice( func_get_args(), 1 ); // phpcs:ignore PHPCompatibility.FunctionUse.ArgumentFunctionsReportCurrentValue.NeedsInspection

wp-includes/default-constants.php

@@ -95,8 +95,10 @@ function wp_initial_constants() {
 		}
 	}
 
-	// Add define( 'WP_DEBUG_DISPLAY', null ); to wp-config.php to use the globally configured setting
+	/*
-	// for 'display_errors' and not force errors to be displayed. Use false to force 'display_errors' off.
+	 * Add define( 'WP_DEBUG_DISPLAY', null ); to wp-config.php to use the globally configured setting
+	 * for 'display_errors' and not force errors to be displayed. Use false to force 'display_errors' off.
+	 */
 	if ( ! defined( 'WP_DEBUG_DISPLAY' ) ) {
 		define( 'WP_DEBUG_DISPLAY', true );
 	}
@@ -110,8 +112,10 @@ function wp_initial_constants() {
 		define( 'WP_CACHE', false );
 	}
 
-	// Add define( 'SCRIPT_DEBUG', true ); to wp-config.php to enable loading of non-minified,
+	/*
-	// non-concatenated scripts and stylesheets.
+	 * Add define( 'SCRIPT_DEBUG', true ); to wp-config.php to enable loading of non-minified,
+	 * non-concatenated scripts and stylesheets.
+	 */
 	if ( ! defined( 'SCRIPT_DEBUG' ) ) {
 		if ( ! empty( $wp_version ) ) {
 			$develop_src = str_contains( $wp_version, '-src' );

wp-includes/embed.php

@@ -510,11 +510,13 @@ function get_post_embed_html( $width, $height, $post = null ) {
 		esc_attr( $secret )
 	);
 
-	// Note that the script must be placed after the <blockquote> and <iframe> due to a regexp parsing issue in
+	/*
-	// `wp_filter_oembed_result()`. Because of the regex pattern starts with `|(<blockquote>.*?</blockquote>)?.*|`
+	 * Note that the script must be placed after the <blockquote> and <iframe> due to a regexp parsing issue in
-	// wherein the <blockquote> is marked as being optional, if it is not at the beginning of the string then the group
+	 * `wp_filter_oembed_result()`. Because of the regex pattern starts with `|(<blockquote>.*?</blockquote>)?.*|`
-	// will fail to match and everything will be matched by `.*` and not included in the group. This regex issue goes
+	 * wherein the <blockquote> is marked as being optional, if it is not at the beginning of the string then the group
-	// back to WordPress 4.4, so in order to not break older installs this script must come at the end.
+	 * will fail to match and everything will be matched by `.*` and not included in the group. This regex issue goes
+	 * back to WordPress 4.4, so in order to not break older installs this script must come at the end.
+	 */
 	$output .= wp_get_inline_script_tag(
 		file_get_contents( ABSPATH . WPINC . '/js/wp-embed' . wp_scripts_get_suffix() . '.js' )
 	);

wp-includes/feed.php

@@ -797,8 +797,10 @@ function fetch_feed( $url ) {
 	$feed = new SimplePie();
 
 	$feed->set_sanitize_class( 'WP_SimplePie_Sanitize_KSES' );
-	// We must manually overwrite $feed->sanitize because SimplePie's constructor
+	/*
-	// sets it before we have a chance to set the sanitization class.
+	 * We must manually overwrite $feed->sanitize because SimplePie's constructor
+	 * sets it before we have a chance to set the sanitization class.
+	 */
 	$feed->sanitize = new WP_SimplePie_Sanitize_KSES();
 
 	// Register the cache handler using the recommended method for SimplePie 1.3 or later.

wp-includes/version.php

@@ -16,7 +16,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '6.3-beta3-56179';
+$wp_version = '6.3-beta3-56180';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.