Docs: Improve some DocBlocks and inline comments per the documentatio…

…n standards.

Follow-up to [56834], [56836], [56837], [56838].

Props kebbet, costdev, mukesh27, SergeyBiryukov.
See #59651.

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

src/wp-admin/includes/class-wp-comments-list-table.php

@@ -662,7 +662,7 @@ public function single_row( $item ) {
 				current_user_can( 'read_post', $comment->comment_post_ID )
 			)
 		) {
-			// The user has access to the post
+			// The user has access to the post and thus can see comments.
 		} else {
 			return false;
 		}

src/wp-admin/includes/class-wp-list-table.php

@@ -860,7 +860,7 @@ protected function comments_bubble( $post_id, $pending_comments ) {
 				current_user_can( 'read_post', $post_id )
 			)
 		) {
-			// The user has access to the post and thus can see comments
+			// The user has access to the post and thus can see comments.
 		} else {
 			return false;
 		}

src/wp-admin/includes/user.php

@@ -638,7 +638,7 @@ function admin_created_user_email( $text ) {
  *
  * @since 5.6.0
  * @since 6.2.0 Allow insecure HTTP connections for the local environment.
- * @since 6.3.2 Validates the success and reject URLs to prevent javascript pseudo protocol being executed.
+ * @since 6.3.2 Validates the success and reject URLs to prevent `javascript` pseudo protocol from being executed.
  *
  * @param array   $request {
  *     The array of request data. All arguments are optional and may be empty.
@@ -700,12 +700,11 @@ function wp_is_authorize_application_password_request_valid( $request, $user ) {
 }
 
 /**
- * Validates the redirect URL protocol scheme. The protocol can be anything except http and javascript.
+ * Validates the redirect URL protocol scheme. The protocol can be anything except `http` and `javascript`.
  *
  * @since 6.3.2
  *
- * @param string $url - The redirect URL to be validated.
- *
+ * @param string $url The redirect URL to be validated.
  * @return true|WP_Error True if the redirect URL is valid, a WP_Error object otherwise.
  */
 function wp_is_authorize_application_redirect_url_valid( $url ) {
@@ -728,16 +727,17 @@ function wp_is_authorize_application_redirect_url_valid( $url ) {
 	 *
 	 * @since 6.3.2
 	 *
-	 * @param string[]  $bad_protocols Array of invalid protocols.
-	 * @param string    $url The redirect URL to be validated.
+	 * @param string[] $bad_protocols Array of invalid protocols.
+	 * @param string   $url The redirect URL to be validated.
 	 */
-	$invalid_protocols = array_map( 'strtolower', apply_filters( 'wp_authorize_application_redirect_url_invalid_protocols', $bad_protocols, $url ) );
+	$invalid_protocols = apply_filters( 'wp_authorize_application_redirect_url_invalid_protocols', $bad_protocols, $url );
+	$invalid_protocols = array_map( 'strtolower', $invalid_protocols );
 
 	$scheme   = wp_parse_url( $url, PHP_URL_SCHEME );
 	$host     = wp_parse_url( $url, PHP_URL_HOST );
 	$is_local = 'local' === wp_get_environment_type();
 
-	// validates if the proper URI format is applied to the $url
+	// Validates if the proper URI format is applied to the URL.
 	if ( empty( $host ) || empty( $scheme ) || in_array( strtolower( $scheme ), $invalid_protocols, true ) ) {
 		return new WP_Error(
 			'invalid_redirect_url_format',

src/wp-includes/blocks.php

@@ -1971,13 +1971,14 @@ function get_comments_pagination_arrow( $block, $pagination_type = 'next' ) {
 
 /**
  * Strips all HTML from the content of footnotes, and sanitizes the ID.
+ *
  * This function expects slashed data on the footnotes content.
  *
  * @access private
  * @since 6.3.2
  *
- * @param string $footnotes JSON encoded string of an array containing the content and ID of each footnote.
- * @return string Filtered content without any HTML on the footnote content and with the sanitized id.
+ * @param string $footnotes JSON-encoded string of an array containing the content and ID of each footnote.
+ * @return string Filtered content without any HTML on the footnote content and with the sanitized ID.
  */
 function _wp_filter_post_meta_footnotes( $footnotes ) {
 	$footnotes_decoded = json_decode( $footnotes, true );
@@ -1997,7 +1998,7 @@ function _wp_filter_post_meta_footnotes( $footnotes ) {
 }
 
 /**
- * Adds the filters to filter footnotes meta field.
+ * Adds the filters for footnotes meta field.
  *
  * @access private
  * @since 6.3.2
@@ -2007,7 +2008,7 @@ function _wp_footnotes_kses_init_filters() {
 }
 
 /**
- * Removes the filters that filter footnotes meta field.
+ * Removes the filters for footnotes meta field.
  *
  * @access private
  * @since 6.3.2
@@ -2017,7 +2018,7 @@ function _wp_footnotes_remove_filters() {
 }
 
 /**
- * Registers the filter of footnotes meta field if the user does not have unfiltered_html capability.
+ * Registers the filter of footnotes meta field if the user does not have `unfiltered_html` capability.
  *
  * @access private
  * @since 6.3.2
@@ -2030,12 +2031,12 @@ function _wp_footnotes_kses_init() {
 }
 
 /**
- * Initializes footnotes meta field filters when imported data should be filtered.
+ * Initializes the filters for footnotes meta field when imported data should be filtered.
  *
- * This filter is the last being executed on force_filtered_html_on_import.
- * If the input of the filter is true it means we are in an import situation and should
- * enable kses, independently of the user capabilities.
- * So in that case we call _wp_footnotes_kses_init_filters;
+ * This filter is the last one being executed on {@see 'force_filtered_html_on_import'}.
+ * If the input of the filter is true, it means we are in an import situation and should
+ * enable kses, independently of the user capabilities. So in that case we call
+ * _wp_footnotes_kses_init_filters().
  *
  * @access private
  * @since 6.3.2
@@ -2044,7 +2045,7 @@ function _wp_footnotes_kses_init() {
  * @return string Input argument of the filter.
  */
 function _wp_footnotes_force_filtered_html_on_import_filter( $arg ) {
-	// force_filtered_html_on_import is true we need to init the global styles kses filters.
+	// If `force_filtered_html_on_import` is true, we need to init the global styles kses filters.
 	if ( $arg ) {
 		_wp_footnotes_kses_init_filters();
 	}

src/wp-includes/media.php

@@ -2636,10 +2636,10 @@ function gallery_shortcode( $attr ) {
 	if ( ! empty( $post_parent_id ) ) {
 		$post_parent = get_post( $post_parent_id );
 
-		// terminate the shortcode execution if user cannot read the post or password-protected
-		if (
-		( ! is_post_publicly_viewable( $post_parent->ID ) && ! current_user_can( 'read_post', $post_parent->ID ) )
-		|| post_password_required( $post_parent ) ) {
+		// Terminate the shortcode execution if the user cannot read the post or it is password-protected.
+		if ( ! is_post_publicly_viewable( $post_parent->ID ) && ! current_user_can( 'read_post', $post_parent->ID )
+			|| post_password_required( $post_parent )
+		) {
 			return '';
 		}
 	}
@@ -2979,7 +2979,7 @@ function wp_playlist_shortcode( $attr ) {
 	if ( ! empty( $args['post_parent'] ) ) {
 		$post_parent = get_post( $id );
 
-		// terminate the shortcode execution if user cannot read the post or password-protected
+		// Terminate the shortcode execution if the user cannot read the post or it is password-protected.
 		if ( ! current_user_can( 'read_post', $post_parent->ID ) || post_password_required( $post_parent ) ) {
 			return '';
 		}

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

@@ -467,17 +467,19 @@ public function serve_request( $path = null ) {
 		$this->set_status( $code );
 
 		/**
-		 * Filters whether to send nocache headers on a REST API request.
+		 * Filters whether to send no-cache headers on a REST API request.
 		 *
 		 * @since 4.4.0
-		 * @since 6.3.2 Moved the block to catch the filter added on rest_cookie_check_errors() from rest-api.php
+		 * @since 6.3.2 Moved the block to catch the filter added on rest_cookie_check_errors() from wp-includes/rest-api.php.
 		 *
 		 * @param bool $rest_send_nocache_headers Whether to send no-cache headers.
 		 */
 		$send_no_cache_headers = apply_filters( 'rest_send_nocache_headers', is_user_logged_in() );
 
-		// send no cache headers if the $send_no_cache_headers is true
-		// OR if the HTTP_X_HTTP_METHOD_OVERRIDE is used but resulted a 4x response code.
+		/*
+		 * Send no-cache headers if $send_no_cache_headers is true,
+		 * OR if the HTTP_X_HTTP_METHOD_OVERRIDE is used but resulted a 4xx response code.
+		 */
 		if ( $send_no_cache_headers || ( true === $method_overridden && strpos( $code, '4' ) === 0 ) ) {
 			foreach ( wp_get_nocache_headers() as $header => $header_value ) {
 				if ( empty( $header_value ) ) {