Changeset 47122 for trunk/src/wp-includes/rest-api.php

Timestamp:

01/29/2020 12:43:23 AM (7 years ago)

Author:

SergeyBiryukov

Message:

Docs: Improve inline comments per the documentation standards.

Includes minor code layout fixes for better readability.

See #48303.

File:

• trunk/src/wp-includes/rest-api.php (modified) (14 diffs)

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

@@ -74 +74 @@
                 'args'     => array(),
         );
+
         foreach ( $args as $key => &$arg_group ) {
                 if ( ! is_numeric( $key ) ) {
@@ -361 +362 @@
         } else {
                 $url = trailingslashit( get_home_url( $blog_id, '', $scheme ) );
-                // nginx only allows HTTP/1.0 methods when redirecting from / to /index.php
+                // nginx only allows HTTP/1.0 methods when redirecting from / to /index.php.
                 // To work around this, we manually add index.php to the URL, avoiding the redirect.
                 if ( 'index.php' !== substr( $url, 9 ) ) {
@@ -378 +379 @@
 
         if ( is_admin() && force_ssl_admin() ) {
-                // In this situation the home URL may be http:, and `is_ssl()` may be
-                // false, but the admin is served over https: (one way or another), so
-                // REST API usage will be blocked by browsers unless it is also served
-                // over HTTPS.
+                /*
+                 * In this situation the home URL may be http:, and `is_ssl()` may be false,
+                 * but the admin is served over https: (one way or another), so REST API usage
+                 * will be blocked by browsers unless it is also served over HTTPS.
+                 */
                 $url = set_url_scheme( $url, 'https' );
         }
@@ -582 +584 @@
 
         if ( $origin ) {
-                // Requests from file:// and data: URLs send "Origin: null"
+                // Requests from file:// and data: URLs send "Origin: null".
                 if ( 'null' !== $origin ) {
                         $origin = esc_url_raw( $origin );
@@ -633 +635 @@
 
                 foreach ( $endpoints as $endpoint ) {
-                        // Remove the redundant preg_match argument.
+                        // Remove the redundant preg_match() argument.
                         unset( $args[0] );
 
@@ -792 +794 @@
                 return true;
         }
+
         foreach ( $fields as $accepted_field ) {
                 // Check to see if $field is the parent of any item in $fields.
@@ -798 +801 @@
                         return true;
                 }
-                // Conversely, if "parent" is accepted, all "parent.child" fields should
-                // also be accepted.
+                // Conversely, if "parent" is accepted, all "parent.child" fields
+                // should also be accepted.
                 if ( strpos( $field, "$accepted_field." ) === 0 ) {
                         return true;
                 }
         }
+
         return false;
 }
@@ -980 +984 @@
  */
 function rest_get_date_with_gmt( $date, $is_utc = false ) {
-        // Whether or not the original date actually has a timezone string
-        // changes the way we need to do timezone conversion.  Store this info
-        // before parsing the date, and use it later.
+        /*
+         * Whether or not the original date actually has a timezone string
+         * changes the way we need to do timezone conversion.
+         * Store this info before parsing the date, and use it later.
+         */
         $has_timezone = preg_match( '#(Z|[+-]\d{2}(:\d{2})?)$#', $date );
 
@@ -991 +997 @@
         }
 
-        // At this point $date could either be a local date (if we were passed a
-        // *local* date without a timezone offset) or a UTC date (otherwise).
-        // Timezone conversion needs to be handled differently between these two
-        // cases.
+        /*
+         * At this point $date could either be a local date (if we were passed
+         * a *local* date without a timezone offset) or a UTC date (otherwise).
+         * Timezone conversion needs to be handled differently between these two cases.
+         */
         if ( ! $is_utc && ! $has_timezone ) {
                 $local = gmdate( 'Y-m-d H:i:s', $date );
@@ -1229 +1236 @@
                         $value = wp_parse_list( $value );
                 }
+
                 if ( ! wp_is_numeric_array( $value ) ) {
                         /* translators: 1: Parameter, 2: Type name. */
                         return new WP_Error( 'rest_invalid_param', sprintf( __( '%1$s is not of type %2$s.' ), $param, 'array' ) );
                 }
+
                 foreach ( $value as $index => $v ) {
                         $is_valid = rest_validate_value_from_schema( $v, $args['items'], $param . '[' . $index . ']' );
@@ -1391 +1400 @@
 function rest_sanitize_value_from_schema( $value, $args ) {
         if ( is_array( $args['type'] ) ) {
-                // Determine which type the value was validated against, and use that type when performing sanitization
+                // Determine which type the value was validated against,
+                // and use that type when performing sanitization.
                 $validated_type = '';
 
@@ -1415 +1425 @@
                         return (array) $value;
                 }
+
                 $value = wp_parse_list( $value );
                 foreach ( $value as $index => $v ) {
                         $value[ $index ] = rest_sanitize_value_from_schema( $v, $args['items'] );
                 }
-                // Normalize to numeric array so nothing unexpected
-                // is in the keys.
+
+                // Normalize to numeric array so nothing unexpected is in the keys.
                 $value = array_values( $value );
                 return $value;
@@ -1475 +1486 @@
 
                         case 'email':
-                                /*
-                                 * sanitize_email() validates, which would be unexpected.
-                                 */
+                                // sanitize_email() validates, which would be unexpected.
                                 return sanitize_text_field( $value );
 
@@ -1506 +1515 @@
  */
 function rest_preload_api_request( $memo, $path ) {
-        // array_reduce() doesn't support passing an array in PHP 5.2, so we need to make sure we start with one.
+        // array_reduce() doesn't support passing an array in PHP 5.2,
+        // so we need to make sure we start with one.
         if ( ! is_array( $memo ) ) {
                 $memo = array();