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], [56192].

Props costdev, audrasjb.
See #58459.




git-svn-id: https://develop.svn.wordpress.org/trunk@56193 602fd350-edb4-49c9-b593-d223f7449a82

Author: audrasjb

src/wp-includes/customize/class-wp-customize-header-image-setting.php

@@ -45,8 +45,10 @@ public function update( $value ) {
 			$custom_image_header    = new Custom_Image_Header( $admin_head_callback, $admin_preview_callback );
 		}
 
-		// If the value doesn't exist (removed or random),
-		// use the header_image value.
+		/*
+		 * If the value doesn't exist (removed or random),
+		 * use the header_image value.
+		 */
 		if ( ! $value ) {
 			$value = $this->manager->get_setting( 'header_image' )->post_value();
 		}

src/wp-includes/customize/class-wp-customize-media-control.php

@@ -88,8 +88,10 @@ public function to_json() {
 
 		if ( is_object( $this->setting ) ) {
 			if ( $this->setting->default ) {
-				// Fake an attachment model - needs all fields used by template.
-				// Note that the default value must be a URL, NOT an attachment ID.
+				/*
+				 * Fake an attachment model - needs all fields used by template.
+				 * Note that the default value must be a URL, NOT an attachment ID.
+				 */
 				$ext  = substr( $this->setting->default, -3 );
 				$type = in_array( $ext, array( 'jpg', 'png', 'gif', 'bmp', 'webp' ), true ) ? 'image' : 'document';
 

src/wp-includes/customize/class-wp-customize-themes-section.php

@@ -184,8 +184,10 @@ protected function filter_bar_content_template() {
 	 * @since 4.9.0
 	 */
 	protected function filter_drawer_content_template() {
-		// @todo Use the .org API instead of the local core feature list.
-		// The .org API is currently outdated and will be reconciled when the .org themes directory is next redesigned.
+		/*
+		 * @todo Use the .org API instead of the local core feature list.
+		 * The .org API is currently outdated and will be reconciled when the .org themes directory is next redesigned.
+		 */
 		$feature_list = get_theme_feature_list( false );
 		?>
 		<# if ( 'wporg' === data.action ) { #>

src/wp-includes/rest-api/class-wp-rest-request.php

@@ -473,8 +473,10 @@ public function get_params() {
 
 		$params = array();
 		foreach ( $order as $type ) {
-			// array_merge() / the "+" operator will mess up
-			// numeric keys, so instead do a manual foreach.
+			/*
+			 * array_merge() / the "+" operator will mess up
+			 * numeric keys, so instead do a manual foreach.
+			 */
 			foreach ( (array) $this->params[ $type ] as $key => $value ) {
 				$params[ $key ] = $value;
 			}

src/wp-includes/rest-api/class-wp-rest-server.php

@@ -701,8 +701,10 @@ protected function embed_links( $data, $embed = true ) {
 		$embedded = array();
 
 		foreach ( $data['_links'] as $rel => $links ) {
-			// If a list of relations was specified, and the link relation
-			// is not in the list of allowed relations, don't process the link.
+			/*
+			 * If a list of relations was specified, and the link relation
+			 * is not in the list of allowed relations, don't process the link.
+			 */
 			if ( is_array( $embed ) && ! in_array( $rel, $embed, true ) ) {
 				continue;
 			}

src/wp-includes/rest-api/endpoints/class-wp-rest-attachments-controller.php

@@ -202,17 +202,21 @@ public function create_item( $request ) {
 		wp_after_insert_post( $attachment, false, null );
 
 		if ( defined( 'REST_REQUEST' ) && REST_REQUEST ) {
-			// Set a custom header with the attachment_id.
-			// Used by the browser/client to resume creating image sub-sizes after a PHP fatal error.
+			/*
+			 * Set a custom header with the attachment_id.
+			 * Used by the browser/client to resume creating image sub-sizes after a PHP fatal error.
+			 */
 			header( 'X-WP-Upload-Attachment-ID: ' . $attachment_id );
 		}
 
 		// Include media and image functions to get access to wp_generate_attachment_metadata().
 		require_once ABSPATH . 'wp-admin/includes/media.php';
 		require_once ABSPATH . 'wp-admin/includes/image.php';
 
-		// Post-process the upload (create image sub-sizes, make PDF thumbnails, etc.) and insert attachment meta.
-		// At this point the server may run out of resources and post-processing of uploaded images may fail.
+		/*
+		 * Post-process the upload (create image sub-sizes, make PDF thumbnails, etc.) and insert attachment meta.
+		 * At this point the server may run out of resources and post-processing of uploaded images may fail.
+		 */
 		wp_update_attachment_metadata( $attachment_id, wp_generate_attachment_metadata( $attachment_id, $file ) );
 
 		$response = $this->prepare_item_for_response( $attachment, $request );
@@ -562,8 +566,10 @@ public function edit_media_item( $request ) {
 		$image_ext  = pathinfo( $image_file, PATHINFO_EXTENSION );
 		$image_name = wp_basename( $image_file, ".{$image_ext}" );
 
-		// Do not append multiple `-edited` to the file name.
-		// The user may be editing a previously edited image.
+		/*
+		 * Do not append multiple `-edited` to the file name.
+		 * The user may be editing a previously edited image.
+		 */
 		if ( preg_match( '/-edited(-\d+)?$/', $image_name ) ) {
 			// Remove any `-1`, `-2`, etc. `wp_unique_filename()` will add the proper number.
 			$image_name = preg_replace( '/-edited(-\d+)?$/', '-edited', $image_name );
@@ -625,8 +631,10 @@ public function edit_media_item( $request ) {
 		}
 
 		if ( defined( 'REST_REQUEST' ) && REST_REQUEST ) {
-			// Set a custom header with the attachment_id.
-			// Used by the browser/client to resume creating image sub-sizes after a PHP fatal error.
+			/*
+			 * Set a custom header with the attachment_id.
+			 * Used by the browser/client to resume creating image sub-sizes after a PHP fatal error.
+			 */
 			header( 'X-WP-Upload-Attachment-ID: ' . $new_attachment_id );
 		}
 

src/wp-includes/rest-api/endpoints/class-wp-rest-autosaves-controller.php

@@ -229,8 +229,10 @@ public function create_item( $request ) {
 		$is_draft  = 'draft' === $post->post_status || 'auto-draft' === $post->post_status;
 
 		if ( $is_draft && (int) $post->post_author === $user_id && ! $post_lock ) {
-			// Draft posts for the same author: autosaving updates the post and does not create a revision.
-			// Convert the post object to an array and add slashes, wp_update_post() expects escaped array.
+			/*
+			 * Draft posts for the same author: autosaving updates the post and does not create a revision.
+			 * Convert the post object to an array and add slashes, wp_update_post() expects escaped array.
+			 */
 			$autosave_id = wp_update_post( wp_slash( (array) $prepared_post ), true );
 		} else {
 			// Non-draft posts: create or update the post autosave.

src/wp-includes/rest-api/endpoints/class-wp-rest-comments-controller.php

@@ -1761,8 +1761,10 @@ protected function check_read_post_permission( $post, $request ) {
 
 		$posts_controller = $post_type->get_rest_controller();
 
-		// Ensure the posts controller is specifically a WP_REST_Posts_Controller instance
-		// before using methods specific to that controller.
+		/*
+		 * Ensure the posts controller is specifically a WP_REST_Posts_Controller instance
+		 * before using methods specific to that controller.
+		 */
 		if ( ! $posts_controller instanceof WP_REST_Posts_Controller ) {
 			$posts_controller = new WP_REST_Posts_Controller( $post->post_type );
 		}

src/wp-includes/rest-api/endpoints/class-wp-rest-controller.php

@@ -576,8 +576,10 @@ public function get_fields_for_response( $request ) {
 		$additional_fields = $this->get_additional_fields();
 
 		foreach ( $additional_fields as $field_name => $field_options ) {
-			// For back-compat, include any field with an empty schema
-			// because it won't be present in $this->get_item_schema().
+			/*
+			 * For back-compat, include any field with an empty schema
+			 * because it won't be present in $this->get_item_schema().
+			 */
 			if ( is_null( $field_options['schema'] ) ) {
 				$properties[ $field_name ] = $field_options;
 			}
@@ -630,8 +632,10 @@ static function( $response_fields, $field ) use ( $fields ) {
 				}
 				// Check for nested fields if $field is not a direct match.
 				$nested_fields = explode( '.', $field );
-				// A nested field is included so long as its top-level property
-				// is present in the schema.
+				/*
+				 * A nested field is included so long as its top-level property
+				 * is present in the schema.
+				 */
 				if ( in_array( $nested_fields[0], $fields, true ) ) {
 					$response_fields[] = $field;
 				}

src/wp-includes/rest-api/endpoints/class-wp-rest-global-styles-controller.php

@@ -61,8 +61,10 @@ public function register_routes() {
 			sprintf(
 				'/%s/themes/(?P<stylesheet>%s)',
 				$this->rest_base,
-				// Matches theme's directory: `/themes/<subdirectory>/<theme>/` or `/themes/<theme>/`.
-				// Excludes invalid directory name characters: `/:<>*?"|`.
+				/*
+				 * Matches theme's directory: `/themes/<subdirectory>/<theme>/` or `/themes/<theme>/`.
+				 * Excludes invalid directory name characters: `/:<>*?"|`.
+				 */
 				'[^\/:<>\*\?"\|]+(?:\/[^\/:<>\*\?"\|]+)?'
 			),
 			array(
@@ -565,8 +567,10 @@ public function get_item_schema() {
 	 * @return true|WP_Error True if the request has read access for the item, WP_Error object otherwise.
 	 */
 	public function get_theme_item_permissions_check( $request ) {
-		// Verify if the current user has edit_theme_options capability.
-		// This capability is required to edit/view/delete templates.
+		/*
+		 * Verify if the current user has edit_theme_options capability.
+		 * This capability is required to edit/view/delete templates.
+		 */
 		if ( ! current_user_can( 'edit_theme_options' ) ) {
 			return new WP_Error(
 				'rest_cannot_manage_global_styles',
@@ -638,8 +642,10 @@ public function get_theme_item( $request ) {
 	 * @return true|WP_Error True if the request has read access for the item, WP_Error object otherwise.
 	 */
 	public function get_theme_items_permissions_check( $request ) { // phpcs:ignore VariableAnalysis.CodeAnalysis.VariableAnalysis.UnusedVariable
-		// Verify if the current user has edit_theme_options capability.
-		// This capability is required to edit/view/delete templates.
+		/*
+		 * Verify if the current user has edit_theme_options capability.
+		 * This capability is required to edit/view/delete templates.
+		 */
 		if ( ! current_user_can( 'edit_theme_options' ) ) {
 			return new WP_Error(
 				'rest_cannot_manage_global_styles',

src/wp-includes/rest-api/endpoints/class-wp-rest-posts-controller.php

@@ -1063,8 +1063,10 @@ public function delete_item( $request ) {
 				);
 			}
 
-			// (Note that internally this falls through to `wp_delete_post()`
-			// if the Trash is disabled.)
+			/*
+			 * (Note that internally this falls through to `wp_delete_post()`
+			 * if the Trash is disabled.)
+			 */
 			$result   = wp_trash_post( $id );
 			$post     = get_post( $id );
 			$response = $this->prepare_item_for_response( $post, $request );
@@ -1269,8 +1271,10 @@ protected function prepare_item_for_database( $request ) {
 			}
 		}
 
-		// Sending a null date or date_gmt value resets date and date_gmt to their
-		// default values (`0000-00-00 00:00:00`).
+		/*
+		 * Sending a null date or date_gmt value resets date and date_gmt to their
+		 * default values (`0000-00-00 00:00:00`).
+		 */
 		if (
 			( ! empty( $schema['properties']['date_gmt'] ) && $request->has_param( 'date_gmt' ) && null === $request['date_gmt'] ) ||
 			( ! empty( $schema['properties']['date'] ) && $request->has_param( 'date' ) && null === $request['date'] )