Make WordPress Core

Changeset 56192


Ignore:
Timestamp:
07/10/2023 10:46:22 PM (3 years ago)
Author:
audrasjb
Message:

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

Props costdev, audrasjb.
See #58459.

Location:
trunk/src/wp-includes
Files:
12 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-includes/ms-default-constants.php

    r53699 r56192  
    2929        }
    3030
    31         // Note, the main site in a post-MU network uses wp-content/uploads.
    32         // This is handled in wp_upload_dir() by ignoring UPLOADS for this case.
     31        /*
     32         * Note, the main site in a post-MU network uses wp-content/uploads.
     33         * This is handled in wp_upload_dir() by ignoring UPLOADS for this case.
     34         */
    3335        if ( ! defined( 'UPLOADS' ) ) {
    3436                $site_id = get_current_blog_id();
  • trunk/src/wp-includes/ms-functions.php

    r56019 r56192  
    246246        do_action( 'remove_user_from_blog', $user_id, $blog_id, $reassign );
    247247
    248         // If being removed from the primary blog, set a new primary
    249         // if the user is assigned to multiple blogs.
     248        /*
     249         * If being removed from the primary blog, set a new primary
     250         * if the user is assigned to multiple blogs.
     251         */
    250252        $primary_blog = get_user_meta( $user_id, 'primary_blog', true );
    251253        if ( $primary_blog == $blog_id ) {
     
    718720        }
    719721
    720         // Has someone already signed up for this domain?
    721         // TODO: Check email too?
     722        /*
     723         * Has someone already signed up for this domain?
     724         * TODO: Check email too?
     725         */
    722726        $signup = $wpdb->get_row( $wpdb->prepare( "SELECT * FROM $wpdb->signups WHERE domain = %s AND path = %s", $mydomain, $path ) );
    723727        if ( $signup instanceof stdClass ) {
     
    19401944        $most_recent_post = array();
    19411945
    1942         // Walk through each blog and get the most recent post
    1943         // published by $user_id.
     1946        /*
     1947         * Walk through each blog and get the most recent post
     1948         * published by $user_id.
     1949         */
    19441950        foreach ( (array) $user_blogs as $blog ) {
    19451951                $prefix      = $wpdb->get_blog_prefix( $blog->userblog_id );
  • trunk/src/wp-includes/ms-load.php

    r55990 r56192  
    227227         */
    228228
    229         // Either www or non-www is supported, not both. If a www domain is requested,
    230         // query for both to provide the proper redirect.
     229        /*
     230         * Either www or non-www is supported, not both. If a www domain is requested,
     231         * query for both to provide the proper redirect.
     232         */
    231233        $domains = array( $domain );
    232234        if ( str_starts_with( $domain, 'www.' ) ) {
     
    311313                        $current_blog = get_site_by_path( $domain, $path );
    312314                } elseif ( '/' !== $current_site->path && 0 === strcasecmp( $current_site->domain, $domain ) && 0 === stripos( $path, $current_site->path ) ) {
    313                         // If the current network has a path and also matches the domain and path of the request,
    314                         // we need to look for a site using the first path segment following the network's path.
     315                        /*
     316                         * If the current network has a path and also matches the domain and path of the request,
     317                         * we need to look for a site using the first path segment following the network's path.
     318                         */
    315319                        $current_blog = get_site_by_path( $domain, $path, 1 + count( explode( '/', trim( $current_site->path, '/' ) ) ) );
    316320                } else {
  • trunk/src/wp-includes/ms-site.php

    r55747 r56192  
    115115                }
    116116
    117                 // Rebuild the data expected by the `wpmu_new_blog` hook prior to 5.1.0 using allowed keys.
    118                 // The `$allowed_data_fields` matches the one used in `wpmu_create_blog()`.
     117                /*
     118                 * Rebuild the data expected by the `wpmu_new_blog` hook prior to 5.1.0 using allowed keys.
     119                 * The `$allowed_data_fields` matches the one used in `wpmu_create_blog()`.
     120                 */
    119121                $allowed_data_fields = array( 'public', 'archived', 'mature', 'spam', 'deleted', 'lang_id' );
    120122                $meta                = array_merge( array_intersect_key( $data, array_flip( $allowed_data_fields ) ), $meta );
  • trunk/src/wp-includes/nav-menu.php

    r55962 r56192  
    548548        }
    549549
    550         // Associate the menu item with the menu term.
    551         // Only set the menu term if it isn't set to avoid unnecessary wp_get_object_terms().
     550        /*
     551         * Associate the menu item with the menu term.
     552         * Only set the menu term if it isn't set to avoid unnecessary wp_get_object_terms().
     553         */
    552554        if ( $menu_id && ( ! $update || ! is_object_in_term( $menu_item_db_id, 'nav_menu', (int) $menu->term_id ) ) ) {
    553555                $update_terms = wp_set_object_terms( $menu_item_db_id, array( $menu->term_id ), 'nav_menu' );
  • trunk/src/wp-includes/option.php

    r56061 r56192  
    665665        $value = sanitize_option( $option, $value );
    666666
    667         // Make sure the option doesn't already exist.
    668         // We can check the 'notoptions' cache before we ask for a DB query.
     667        /*
     668         * Make sure the option doesn't already exist.
     669         * We can check the 'notoptions' cache before we ask for a DB query.
     670         */
    669671        $notoptions = wp_cache_get( 'notoptions', 'options' );
    670672
     
    9991001                        $result = add_option( $transient_option, $value, '', $autoload );
    10001002                } else {
    1001                         // If expiration is requested, but the transient has no timeout option,
    1002                         // delete, then re-create transient rather than update.
     1003                        /*
     1004                         * If expiration is requested, but the transient has no timeout option,
     1005                         * delete, then re-create transient rather than update.
     1006                         */
    10031007                        $update = true;
    10041008
     
    15991603                $cache_key = "$network_id:$option";
    16001604
    1601                 // Make sure the option doesn't already exist.
    1602                 // We can check the 'notoptions' cache before we ask for a DB query.
     1605                /*
     1606                 * Make sure the option doesn't already exist.
     1607                 * We can check the 'notoptions' cache before we ask for a DB query.
     1608                 */
    16031609                $notoptions = wp_cache_get( $notoptions_key, 'site-options' );
    16041610
  • trunk/src/wp-includes/pluggable.php

    r56037 r56192  
    268268                } else {
    269269                        if ( ! is_array( $headers ) ) {
    270                                 // Explode the headers out, so this function can take
    271                                 // both string headers and an array of headers.
     270                                /*
     271                                 * Explode the headers out, so this function can take
     272                                 * both string headers and an array of headers.
     273                                 */
    272274                                $tempheaders = explode( "\n", str_replace( "\r\n", "\n", $headers ) );
    273275                        } else {
     
    617619
    618620                if ( null == $user ) {
    619                         // TODO: What should the error message be? (Or would these even happen?)
    620                         // Only needed if all authentication handlers fail to return anything.
     621                        /*
     622                         * TODO: What should the error message be? (Or would these even happen?)
     623                         * Only needed if all authentication handlers fail to return anything.
     624                         */
    621625                        $user = new WP_Error( 'authentication_failed', __( '<strong>Error:</strong> Invalid username, email address or incorrect password.' ) );
    622626                }
     
    15621566                }
    15631567
    1564                 // In PHP 5 parse_url() may fail if the URL query part contains 'http://'.
    1565                 // See https://bugs.php.net/bug.php?id=38143
     1568                /*
     1569                 * In PHP 5 parse_url() may fail if the URL query part contains 'http://'.
     1570                 * See https://bugs.php.net/bug.php?id=38143
     1571                 */
    15661572                $cut  = strpos( $location, '?' );
    15671573                $test = $cut ? substr( $location, 0, $cut ) : $location;
     
    15881594                }
    15891595
    1590                 // Reject if certain components are set but host is not.
    1591                 // This catches URLs like https:host.com for which parse_url() does not set the host field.
     1596                /*
     1597                 * Reject if certain components are set but host is not.
     1598                 * This catches URLs like https:host.com for which parse_url() does not set the host field.
     1599                 */
    15921600                if ( ! isset( $lp['host'] ) && ( isset( $lp['scheme'] ) || isset( $lp['user'] ) || isset( $lp['pass'] ) || isset( $lp['port'] ) ) ) {
    15931601                        return $fallback_url;
     
    17151723                }
    17161724
    1717                 // The blogname option is escaped with esc_html() on the way into the database in sanitize_option().
    1718                 // We want to reverse this for the plain text arena of emails.
     1725                /*
     1726                 * The blogname option is escaped with esc_html() on the way into the database in sanitize_option().
     1727                 * We want to reverse this for the plain text arena of emails.
     1728                 */
    17191729                $blogname        = wp_specialchars_decode( get_option( 'blogname' ), ENT_QUOTES );
    17201730                $comment_content = wp_specialchars_decode( $comment->comment_content );
     
    19041914                $comments_waiting = $wpdb->get_var( "SELECT COUNT(*) FROM $wpdb->comments WHERE comment_approved = '0'" );
    19051915
    1906                 // The blogname option is escaped with esc_html() on the way into the database in sanitize_option().
    1907                 // We want to reverse this for the plain text arena of emails.
     1916                /*
     1917                 * The blogname option is escaped with esc_html() on the way into the database in sanitize_option().
     1918                 * We want to reverse this for the plain text arena of emails.
     1919                 */
    19081920                $blogname        = wp_specialchars_decode( get_option( 'blogname' ), ENT_QUOTES );
    19091921                $comment_content = wp_specialchars_decode( $comment->comment_content );
     
    20432055         */
    20442056        function wp_password_change_notification( $user ) {
    2045                 // Send a copy of password change notification to the admin,
    2046                 // but check to see if it's the admin whose password we're changing, and skip this.
     2057                /*
     2058                 * Send a copy of password change notification to the admin,
     2059                 * but check to see if it's the admin whose password we're changing, and skip this.
     2060                 */
    20472061                if ( 0 !== strcasecmp( $user->user_email, get_option( 'admin_email' ) ) ) {
    20482062                        /* translators: %s: User name. */
    20492063                        $message = sprintf( __( 'Password changed for user: %s' ), $user->user_login ) . "\r\n";
    2050                         // The blogname option is escaped with esc_html() on the way into the database in sanitize_option().
    2051                         // We want to reverse this for the plain text arena of emails.
     2064                        /*
     2065                         * The blogname option is escaped with esc_html() on the way into the database in sanitize_option().
     2066                         * We want to reverse this for the plain text arena of emails.
     2067                         */
    20522068                        $blogname = wp_specialchars_decode( get_option( 'blogname' ), ENT_QUOTES );
    20532069
     
    21162132                $user = get_userdata( $user_id );
    21172133
    2118                 // The blogname option is escaped with esc_html() on the way into the database in sanitize_option().
    2119                 // We want to reverse this for the plain text arena of emails.
     2134                /*
     2135                 * The blogname option is escaped with esc_html() on the way into the database in sanitize_option().
     2136                 * We want to reverse this for the plain text arena of emails.
     2137                 */
    21202138                $blogname = wp_specialchars_decode( get_option( 'blogname' ), ENT_QUOTES );
    21212139
     
    25732591                }
    25742592
    2575                 // If the stored hash is longer than an MD5,
    2576                 // presume the new style phpass portable hash.
     2593                /*
     2594                 * If the stored hash is longer than an MD5,
     2595                 * presume the new style phpass portable hash.
     2596                 */
    25772597                if ( empty( $wp_hasher ) ) {
    25782598                        require_once ABSPATH . WPINC . '/class-phpass.php';
     
    26522672                global $rnd_value;
    26532673
    2654                 // Some misconfigured 32-bit environments (Entropy PHP, for example)
    2655                 // truncate integers larger than PHP_INT_MAX to PHP_INT_MAX rather than overflowing them to floats.
     2674                /*
     2675                 * Some misconfigured 32-bit environments (Entropy PHP, for example)
     2676                 * truncate integers larger than PHP_INT_MAX to PHP_INT_MAX rather than overflowing them to floats.
     2677                 */
    26562678                $max_random_number = 3000000000 === 2147483647 ? (float) '4294967295' : 4294967295; // 4294967295 = 0xffffffff
    26572679
     
    26882710                }
    26892711
    2690                 // Reset $rnd_value after 14 uses.
    2691                 // 32 (md5) + 40 (sha1) + 40 (sha1) / 8 = 14 random numbers from $rnd_value.
     2712                /*
     2713                 * Reset $rnd_value after 14 uses.
     2714                 * 32 (md5) + 40 (sha1) + 40 (sha1) / 8 = 14 random numbers from $rnd_value.
     2715                 */
    26922716                if ( strlen( $rnd_value ) < 8 ) {
    26932717                        if ( defined( 'WP_SETUP_CONFIG' ) ) {
  • trunk/src/wp-includes/post-template.php

    r55988 r56192  
    286286        }
    287287
    288         // Use the globals if the $post parameter was not specified,
    289         // but only after they have been set up in setup_postdata().
     288        /*
     289         * Use the globals if the $post parameter was not specified,
     290         * but only after they have been set up in setup_postdata().
     291         */
    290292        if ( null === $post && did_action( 'the_post' ) ) {
    291293                $elements = compact( 'page', 'more', 'preview', 'pages', 'multipage' );
  • trunk/src/wp-includes/post.php

    r56160 r56192  
    66156615        $post_id = (int) $post_id;
    66166616
    6617         // This uses image_downsize() which also looks for the (very) old format $image_meta['thumb']
    6618         // when the newer format $image_meta['sizes']['thumbnail'] doesn't exist.
     6617        /*
     6618         * This uses image_downsize() which also looks for the (very) old format $image_meta['thumb']
     6619         * when the newer format $image_meta['sizes']['thumbnail'] doesn't exist.
     6620         */
    66196621        $thumbnail_url = wp_get_attachment_image_url( $post_id, 'thumbnail' );
    66206622
  • trunk/src/wp-includes/query.php

    r55526 r56192  
    11401140        $query = $wpdb->prepare( "SELECT post_id FROM $wpdb->postmeta, $wpdb->posts WHERE ID = post_id AND post_type = %s AND meta_key = '_wp_old_slug' AND meta_value = %s", $post_type, get_query_var( 'name' ) );
    11411141
    1142         // If year, monthnum, or day have been specified, make our query more precise
    1143         // just in case there are multiple identical _wp_old_slug values.
     1142        /*
     1143         * If year, monthnum, or day have been specified, make our query more precise
     1144         * just in case there are multiple identical _wp_old_slug values.
     1145         */
    11441146        if ( get_query_var( 'year' ) ) {
    11451147                $query .= $wpdb->prepare( ' AND YEAR(post_date) = %d', get_query_var( 'year' ) );
  • trunk/src/wp-includes/rest-api.php

    r56082 r56192  
    474474        } else {
    475475                $url = trailingslashit( get_home_url( $blog_id, '', $scheme ) );
    476                 // nginx only allows HTTP/1.0 methods when redirecting from / to /index.php.
    477                 // To work around this, we manually add index.php to the URL, avoiding the redirect.
     476                /*
     477                 * nginx only allows HTTP/1.0 methods when redirecting from / to /index.php.
     478                 * To work around this, we manually add index.php to the URL, avoiding the redirect.
     479                 */
    478480                if ( ! str_ends_with( $url, 'index.php' ) ) {
    479481                        $url .= 'index.php';
     
    633635        }
    634636
    635         // While WP_HTTP_Response is the base class of WP_REST_Response, it doesn't provide
    636         // all the required methods used in WP_REST_Server::dispatch().
     637        /*
     638         * While WP_HTTP_Response is the base class of WP_REST_Response, it doesn't provide
     639         * all the required methods used in WP_REST_Server::dispatch().
     640         */
    637641        if ( $response instanceof WP_HTTP_Response ) {
    638642                return new WP_REST_Response(
     
    946950
    947951        foreach ( $fields as $accepted_field ) {
    948                 // Check to see if $field is the parent of any item in $fields.
    949                 // A field "parent" should be accepted if "parent.child" is accepted.
     952                /*
     953                 * Check to see if $field is the parent of any item in $fields.
     954                 * A field "parent" should be accepted if "parent.child" is accepted.
     955                 */
    950956                if ( str_starts_with( $accepted_field, "$field." ) ) {
    951957                        return true;
    952958                }
    953                 // Conversely, if "parent" is accepted, all "parent.child" fields
    954                 // should also be accepted.
     959                /*
     960                 * Conversely, if "parent" is accepted, all "parent.child" fields
     961                 * should also be accepted.
     962                 */
    955963                if ( str_starts_with( $field, "$accepted_field." ) ) {
    956964                        return true;
     
    16101618        );
    16111619
    1612         // Both arrays and objects allow empty strings to be converted to their types.
    1613         // But the best answer for this type is a string.
     1620        /*
     1621         * Both arrays and objects allow empty strings to be converted to their types.
     1622         * But the best answer for this type is a string.
     1623         */
    16141624        if ( '' === $value && in_array( 'string', $types, true ) ) {
    16151625                return 'string';
     
    21922202        }
    21932203
    2194         // The "format" keyword should only be applied to strings. However, for backward compatibility,
    2195         // we allow the "format" keyword if the type keyword was not specified, or was set to an invalid value.
     2204        /*
     2205         * The "format" keyword should only be applied to strings. However, for backward compatibility,
     2206         * we allow the "format" keyword if the type keyword was not specified, or was set to an invalid value.
     2207         */
    21962208        if ( isset( $args['format'] )
    21972209                && ( ! isset( $args['type'] ) || 'string' === $args['type'] || ! in_array( $args['type'], $allowed_types, true ) )
     
    28592871 */
    28602872function rest_preload_api_request( $memo, $path ) {
    2861         // array_reduce() doesn't support passing an array in PHP 5.2,
    2862         // so we need to make sure we start with one.
     2873        /*
     2874         * array_reduce() doesn't support passing an array in PHP 5.2,
     2875         * so we need to make sure we start with one.
     2876         */
    28632877        if ( ! is_array( $memo ) ) {
    28642878                $memo = array();
  • trunk/src/wp-includes/revision.php

    r55988 r56192  
    191191        $return = _wp_put_post_revision( $post );
    192192
    193         // If a limit for the number of revisions to keep has been set,
    194         // delete the oldest ones.
     193        /*
     194         * If a limit for the number of revisions to keep has been set,
     195         * delete the oldest ones.
     196         */
    195197        $revisions_to_keep = wp_revisions_to_keep( $post );
    196198
     
    870872
    871873                if ( ! $locked ) {
    872                         // Can't write to the lock, and can't read the lock.
    873                         // Something broken has happened.
     874                        /*
     875                         * Can't write to the lock, and can't read the lock.
     876                         * Something broken has happened.
     877                         */
    874878                        return false;
    875879                }
     
    900904                }
    901905
    902                 // 1 is the latest revision version, so we're already up to date.
    903                 // No need to add a copy of the post as latest revision.
     906                /*
     907                 * 1 is the latest revision version, so we're already up to date.
     908                 * No need to add a copy of the post as latest revision.
     909                 */
    904910                if ( 0 < $this_revision_version ) {
    905911                        $add_last = false;
Note: See TracChangeset for help on using the changeset viewer.