Changeset 57120

Timestamp:

11/17/2023 01:27:23 PM (11 months ago)

Author:

SergeyBiryukov

Message:

Docs: Improve some DocBlocks and inline comments per the documentation standards.

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

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

Location:

trunk/src

Files:

• wp-admin/includes/class-wp-comments-list-table.php (modified) (1 diff)
• wp-admin/includes/class-wp-list-table.php (modified) (1 diff)
• wp-admin/includes/user.php (modified) (4 diffs)
• wp-includes/blocks.php (modified) (7 diffs)
• wp-includes/media.php (modified) (2 diffs)
• wp-includes/rest-api/class-wp-rest-server.php (modified) (2 diffs)

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

@@ -663 +663 @@
             )
         ) {
-            // The user has access to the post
+            // The user has access to the post and thus can see comments.
         } else {
             return false;

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

@@ -861 +861 @@
             )
         ) {
-            // 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;

trunk/src/wp-admin/includes/user.php

@@ -639 +639 @@
  * @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 {
@@ -701 +701 @@
 
 /**
- * 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.
  */
@@ -729 +728 @@
      * @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 );
@@ -738 +738 @@
     $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(

trunk/src/wp-includes/blocks.php

@@ -1972 +1972 @@
 /**
  * Strips all HTML from the content of footnotes, and sanitizes the ID.
+ *
  * This function expects slashed data on the footnotes content.
  *
@@ -1977 +1978 @@
  * @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 ) {
@@ -1998 +1999 @@
 
 /**
- * Adds the filters to filter footnotes meta field.
+ * Adds the filters for footnotes meta field.
  *
  * @access private
@@ -2008 +2009 @@
 
 /**
- * Removes the filters that filter footnotes meta field.
+ * Removes the filters for footnotes meta field.
  *
  * @access private
@@ -2018 +2019 @@
 
 /**
- * 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
@@ -2031 +2032 @@
 
 /**
- * Initializes footnotes meta field filters 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;
+ * Initializes the filters for footnotes meta field when imported data should be filtered.
+ *
+ * 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
@@ -2045 +2046 @@
  */
 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();

trunk/src/wp-includes/media.php

@@ -2637 +2637 @@
         $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 '';
         }
@@ -2980 +2980 @@
         $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 '';

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

@@ -468 +468 @@
 
         /**
-         * 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.
@@ -477 +477 @@
         $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 ) {