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

Props costdev, audrasjb.
See #58459.



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


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

wp-admin/includes/ms.php

@@ -1005,8 +1005,10 @@ function network_settings_add_js() {
 jQuery( function($) {
 	var languageSelect = $( '#WPLANG' );
 	$( 'form' ).on( 'submit', function() {
-		// Don't show a spinner for English and installed languages,
+		/*
-		// as there is nothing to download.
+		 * Don't show a spinner for English and installed languages,
+		 * as there is nothing to download.
+		 */
 		if ( ! languageSelect.find( 'option:selected' ).data( 'installed' ) ) {
 			$( '#submit', this ).after( '<span class="spinner language-install-spinner is-active" />' );
 		}

wp-admin/includes/nav-menu.php

@@ -1502,8 +1502,10 @@ function _wp_expand_nav_menu_post_data() {
 
 	if ( ! is_null( $data ) && $data ) {
 		foreach ( $data as $post_input_data ) {
-			// For input names that are arrays (e.g. `menu-item-db-id[3][4][5]`),
+			/*
-			// derive the array path keys via regex and set the value in $_POST.
+			 * For input names that are arrays (e.g. `menu-item-db-id[3][4][5]`),
+			 * derive the array path keys via regex and set the value in $_POST.
+			 */
 			preg_match( '#([^\[]*)(\[(.+)\])?#', $post_input_data->name, $matches );
 
 			$array_bits = array( $matches[1] );

wp-admin/includes/options.php

@@ -90,8 +90,10 @@ function options_general_add_js() {
 
 		var languageSelect = $( '#WPLANG' );
 		$( 'form' ).on( 'submit', function() {
-			// Don't show a spinner for English and installed languages,
+			/*
-			// as there is nothing to download.
+			 * Don't show a spinner for English and installed languages,
+			 * as there is nothing to download.
+			 */
 			if ( ! languageSelect.find( 'option:selected' ).data( 'installed' ) ) {
 				$( '#submit', this ).after( '<span class="spinner language-install-spinner is-active" />' );
 			}

wp-admin/includes/plugin-install.php

@@ -486,8 +486,10 @@ function install_plugin_install_status( $api, $loop = false ) {
 				}
 			} else {
 				$key = array_keys( $installed_plugin );
-				// Use the first plugin regardless of the name.
+				/*
-				// Could have issues for multiple plugins in one directory if they share different version numbers.
+				 * Use the first plugin regardless of the name.
+				 * Could have issues for multiple plugins in one directory if they share different version numbers.
+				 */
 				$key = reset( $key );
 
 				$update_file = $api->slug . '/' . $key;

wp-admin/includes/plugin.php

@@ -178,8 +178,10 @@ function _get_plugin_data_markup_translate( $plugin_file, $plugin_data, $markup
 		'title' => true,
 	);
 
-	// Name is marked up inside <a> tags. Don't allow these.
+	/*
-	// Author is too, but some plugins have used <a> here (omitting Author URI).
+	 * Name is marked up inside <a> tags. Don't allow these.
+	 * Author is too, but some plugins have used <a> here (omitting Author URI).
+	 */
 	$plugin_data['Name']   = wp_kses( $plugin_data['Name'], $allowed_tags_in_links );
 	$plugin_data['Author'] = wp_kses( $plugin_data['Author'], $allowed_tags );
 
@@ -969,8 +971,10 @@ function delete_plugins( $plugins, $deprecated = '' ) {
 
 		$this_plugin_dir = trailingslashit( dirname( $plugins_dir . $plugin_file ) );
 
-		// If plugin is in its own directory, recursively delete the directory.
+		/*
-		// Base check on if plugin includes directory separator AND that it's not the root plugin folder.
+		 * If plugin is in its own directory, recursively delete the directory.
+		 * Base check on if plugin includes directory separator AND that it's not the root plugin folder.
+		 */
 		if ( strpos( $plugin_file, '/' ) && $this_plugin_dir !== $plugins_dir ) {
 			$deleted = $wp_filesystem->delete( $this_plugin_dir, true );
 		} else {

wp-admin/includes/post.php

@@ -135,8 +135,10 @@ function _wp_translate_postdata( $update = false, $post_data = null ) {
 
 	$published_statuses = array( 'publish', 'future' );
 
-	// Posts 'submitted for approval' are submitted to $_POST the same as if they were being published.
+	/*
-	// Change status from 'publish' to 'pending' if user lacks permissions to publish or to resave published posts.
+	 * Posts 'submitted for approval' are submitted to $_POST the same as if they were being published.
+	 * Change status from 'publish' to 'pending' if user lacks permissions to publish or to resave published posts.
+	 */
 	if ( isset( $post_data['post_status'] )
 		&& ( in_array( $post_data['post_status'], $published_statuses, true )
 		&& ! current_user_can( $ptype->cap->publish_posts ) )
@@ -1443,8 +1445,10 @@ function get_sample_permalink( $post, $title = null, $name = null ) {
 		$post->post_name   = sanitize_title( $post->post_name ? $post->post_name : $post->post_title, $post->ID );
 	}
 
-	// If the user wants to set a new name -- override the current one.
+	/*
-	// Note: if empty name is supplied -- use the title instead, see #6072.
+	 * If the user wants to set a new name -- override the current one.
+	 * Note: if empty name is supplied -- use the title instead, see #6072.
+	 */
 	if ( ! is_null( $name ) ) {
 		$post->post_name = sanitize_title( $name ? $name : $title, $post->ID );
 	}
@@ -2073,8 +2077,10 @@ function wp_autosave( $post_data ) {
 		// Drafts and auto-drafts are just overwritten by autosave for the same user if the post is not locked.
 		return edit_post( wp_slash( $post_data ) );
 	} else {
-		// Non-drafts or other users' drafts are not overwritten.
+		/*
-		// The autosave is stored in a special post revision for each user.
+		 * Non-drafts or other users' drafts are not overwritten.
+		 * The autosave is stored in a special post revision for each user.
+		 */
 		return wp_create_post_autosave( wp_slash( $post_data ) );
 	}
 }

wp-admin/includes/revision.php

@@ -39,8 +39,10 @@ function wp_get_revision_ui_diff( $post, $compare_from, $compare_to ) {
 		return false;
 	}
 
-	// If comparing revisions, make sure we're dealing with the right post parent.
+	/*
-	// The parent post may be a 'revision' when revisions are disabled and we're looking at autosaves.
+	 * If comparing revisions, make sure we are dealing with the right post parent.
+	 * The parent post may be a 'revision' when revisions are disabled and we're looking at autosaves.
+	 */
 	if ( $compare_from && $compare_from->post_parent !== $post->ID && $compare_from->ID !== $post->ID ) {
 		return false;
 	}
@@ -118,8 +120,10 @@ function wp_get_revision_ui_diff( $post, $compare_from, $compare_to ) {
 		$diff = wp_text_diff( $content_from, $content_to, $args );
 
 		if ( ! $diff && 'post_title' === $field ) {
-			// It's a better user experience to still show the Title, even if it didn't change.
+			/*
-			// No, you didn't see this.
+			 * It's a better user experience to still show the Title, even if it didn't change.
+			 * No, you didn't see this.
+			 */
 			$diff = '<table class="diff"><colgroup><col class="content diffsplit left"><col class="content diffsplit middle"><col class="content diffsplit right"></colgroup><tbody><tr>';
 
 			// In split screen mode, show the title before/after side by side.

wp-admin/includes/schema.php

@@ -548,8 +548,10 @@ function populate_options( array $options = array() ) {
 		// 5.6.0
 		'auto_update_core_dev'            => 'enabled',
 		'auto_update_core_minor'          => 'enabled',
-		// Default to enabled for new installs.
+		/*
-		// See https://core.trac.wordpress.org/ticket/51742.
+		 * Default to enabled for new installs.
+		 * See https://core.trac.wordpress.org/ticket/51742.
+		 */
 		'auto_update_core_major'          => 'enabled',
 
 		// 5.8.0

wp-admin/includes/template.php

@@ -165,8 +165,10 @@ function wp_terms_checklist( $post_id = 0, $args = array() ) {
 	$output = '';
 
 	if ( $parsed_args['checked_ontop'] ) {
-		// Post-process $categories rather than adding an exclude to the get_terms() query
+		/*
-		// to keep the query the same across all posts (for any query cache).
+		 * Post-process $categories rather than adding an exclude to the get_terms() query
+		 * to keep the query the same across all posts (for any query cache).
+		 */
 		$checked_categories = array();
 		$keys               = array_keys( $categories );
 
@@ -1301,8 +1303,10 @@ function do_meta_boxes( $screen, $context, $data_object ) {
 
 	printf( '<div id="%s-sortables" class="meta-box-sortables">', esc_attr( $context ) );
 
-	// Grab the ones the user has manually sorted.
+	/*
-	// Pull them out of their previous context/priority and into the one the user chose.
+	 * Grab the ones the user has manually sorted.
+	 * Pull them out of their previous context/priority and into the one the user chose.
+	 */
 	$sorted = get_user_option( "meta-box-order_$page" );
 
 	if ( ! $already_sorted && $sorted ) {

wp-admin/includes/update-core.php

@@ -1229,8 +1229,10 @@ function update_core( $from, $to ) {
 	/** This filter is documented in wp-admin/includes/update-core.php */
 	apply_filters( 'update_feedback', __( 'Preparing to install the latest version…' ) );
 
-	// Don't copy wp-content, we'll deal with that below.
+	/*
-	// We also copy version.php last so failed updates report their old version.
+	 * Don't copy wp-content, we'll deal with that below.
+	 * We also copy version.php last so failed updates report their old version.
+	 */
 	$skip              = array( 'wp-content', 'wp-includes/version.php' );
 	$check_is_writable = array();
 
@@ -1397,8 +1399,10 @@ function update_core( $from, $to ) {
 			}
 		}
 
-		// If we don't have enough free space, it isn't worth trying again.
+		/*
-		// Unlikely to be hit due to the check in unzip_file().
+		 * If we don't have enough free space, it isn't worth trying again.
+		 * Unlikely to be hit due to the check in unzip_file().
+		 */
 		$available_space = function_exists( 'disk_free_space' ) ? @disk_free_space( ABSPATH ) : false;
 
 		if ( $available_space && $total_size >= $available_space ) {
@@ -1416,8 +1420,10 @@ function update_core( $from, $to ) {
 		}
 	}
 
-	// Custom content directory needs updating now.
+	/*
-	// Copy languages.
+	 * Custom content directory needs updating now.
+	 * Copy languages.
+	 */
 	if ( ! is_wp_error( $result ) && $wp_filesystem->is_dir( $from . $distro . 'wp-content/languages' ) ) {
 		if ( WP_LANG_DIR !== ABSPATH . WPINC . '/languages' || @is_dir( WP_LANG_DIR ) ) {
 			$lang_dir = WP_LANG_DIR;
@@ -1455,8 +1461,10 @@ function update_core( $from, $to ) {
 	// Remove maintenance file, we're done with potential site-breaking changes.
 	$wp_filesystem->delete( $maintenance_file );
 
-	// 3.5 -> 3.5+ - an empty twentytwelve directory was created upon upgrade to 3.5 for some users,
+	/*
-	// preventing installation of Twenty Twelve.
+	 * 3.5 -> 3.5+ - an empty twentytwelve directory was created upon upgrade to 3.5 for some users,
+	 * preventing installation of Twenty Twelve.
+	 */
 	if ( '3.5' === $old_wp_version ) {
 		if ( is_dir( WP_CONTENT_DIR . '/themes/twentytwelve' )
 			&& ! file_exists( WP_CONTENT_DIR . '/themes/twentytwelve/style.css' )

wp-admin/includes/upgrade.php

@@ -440,8 +440,10 @@ Commenter avatars come from <a href="%s">Gravatar</a>.'
 			$wpdb->query( $wpdb->prepare( "DELETE FROM $wpdb->usermeta WHERE user_id != %d AND meta_key = %s", $user_id, $table_prefix . 'user_level' ) );
 			$wpdb->query( $wpdb->prepare( "DELETE FROM $wpdb->usermeta WHERE user_id != %d AND meta_key = %s", $user_id, $table_prefix . 'capabilities' ) );
 
-			// Delete any caps that snuck into the previously active blog. (Hardcoded to blog 1 for now.)
+			/*
-			// TODO: Get previous_blog_id.
+			 * Delete any caps that snuck into the previously active blog. (Hardcoded to blog 1 for now.)
+			 * TODO: Get previous_blog_id.
+			 */
 			if ( ! is_super_admin( $user_id ) && 1 != $user_id ) {
 				$wpdb->delete(
 					$wpdb->usermeta,
@@ -1644,8 +1646,10 @@ function upgrade_290() {
 	global $wp_current_db_version;
 
 	if ( $wp_current_db_version < 11958 ) {
-		// Previously, setting depth to 1 would redundantly disable threading,
+		/*
-		// but now 2 is the minimum depth to avoid confusion.
+		 * Previously, setting depth to 1 would redundantly disable threading,
+		 * but now 2 is the minimum depth to avoid confusion.
+		 */
 		if ( get_option( 'thread_comments_depth' ) == '1' ) {
 			update_option( 'thread_comments_depth', 2 );
 			update_option( 'thread_comments', 0 );
@@ -3331,8 +3335,10 @@ function make_site_theme_from_default( $theme_name, $template ) {
 	$site_dir    = WP_CONTENT_DIR . "/themes/$template";
 	$default_dir = WP_CONTENT_DIR . '/themes/' . WP_DEFAULT_THEME;
 
-	// Copy files from the default theme to the site theme.
+	/*
-	// $files = array( 'index.php', 'comments.php', 'comments-popup.php', 'footer.php', 'header.php', 'sidebar.php', 'style.css' );
+	 * Copy files from the default theme to the site theme.
+	 * $files = array( 'index.php', 'comments.php', 'comments-popup.php', 'footer.php', 'header.php', 'sidebar.php', 'style.css' );
+	 */
 
 	$theme_dir = @opendir( $default_dir );
 	if ( $theme_dir ) {

wp-includes/version.php

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