Make WordPress Core

Changeset 56192


Ignore:
Timestamp:
07/10/2023 10:46:22 PM (9 months 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.