Make WordPress Core

Changeset 57120


Ignore:
Timestamp:
11/17/2023 01:27:23 PM (6 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:
6 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-admin/includes/class-wp-comments-list-table.php

    r56836 r57120  
    663663            )
    664664        ) {
    665             // The user has access to the post
     665            // The user has access to the post and thus can see comments.
    666666        } else {
    667667            return false;
  • trunk/src/wp-admin/includes/class-wp-list-table.php

    r56836 r57120  
    861861            )
    862862        ) {
    863             // The user has access to the post and thus can see comments
     863            // The user has access to the post and thus can see comments.
    864864        } else {
    865865            return false;
  • trunk/src/wp-admin/includes/user.php

    r56837 r57120  
    639639 * @since 5.6.0
    640640 * @since 6.2.0 Allow insecure HTTP connections for the local environment.
    641  * @since 6.3.2 Validates the success and reject URLs to prevent javascript pseudo protocol being executed.
     641 * @since 6.3.2 Validates the success and reject URLs to prevent `javascript` pseudo protocol from being executed.
    642642 *
    643643 * @param array   $request {
     
    701701
    702702/**
    703  * Validates the redirect URL protocol scheme. The protocol can be anything except http and javascript.
     703 * Validates the redirect URL protocol scheme. The protocol can be anything except `http` and `javascript`.
    704704 *
    705705 * @since 6.3.2
    706706 *
    707  * @param string $url - The redirect URL to be validated.
    708  *
     707 * @param string $url The redirect URL to be validated.
    709708 * @return true|WP_Error True if the redirect URL is valid, a WP_Error object otherwise.
    710709 */
     
    729728     * @since 6.3.2
    730729     *
    731      * @param string[]  $bad_protocols Array of invalid protocols.
    732      * @param string    $url The redirect URL to be validated.
     730     * @param string[] $bad_protocols Array of invalid protocols.
     731     * @param string   $url The redirect URL to be validated.
    733732     */
    734     $invalid_protocols = array_map( 'strtolower', apply_filters( 'wp_authorize_application_redirect_url_invalid_protocols', $bad_protocols, $url ) );
     733    $invalid_protocols = apply_filters( 'wp_authorize_application_redirect_url_invalid_protocols', $bad_protocols, $url );
     734    $invalid_protocols = array_map( 'strtolower', $invalid_protocols );
    735735
    736736    $scheme   = wp_parse_url( $url, PHP_URL_SCHEME );
     
    738738    $is_local = 'local' === wp_get_environment_type();
    739739
    740     // validates if the proper URI format is applied to the $url
     740    // Validates if the proper URI format is applied to the URL.
    741741    if ( empty( $host ) || empty( $scheme ) || in_array( strtolower( $scheme ), $invalid_protocols, true ) ) {
    742742        return new WP_Error(
  • trunk/src/wp-includes/blocks.php

    r57066 r57120  
    19721972/**
    19731973 * Strips all HTML from the content of footnotes, and sanitizes the ID.
     1974 *
    19741975 * This function expects slashed data on the footnotes content.
    19751976 *
     
    19771978 * @since 6.3.2
    19781979 *
    1979  * @param string $footnotes JSON encoded string of an array containing the content and ID of each footnote.
    1980  * @return string Filtered content without any HTML on the footnote content and with the sanitized id.
     1980 * @param string $footnotes JSON-encoded string of an array containing the content and ID of each footnote.
     1981 * @return string Filtered content without any HTML on the footnote content and with the sanitized ID.
    19811982 */
    19821983function _wp_filter_post_meta_footnotes( $footnotes ) {
     
    19981999
    19992000/**
    2000  * Adds the filters to filter footnotes meta field.
     2001 * Adds the filters for footnotes meta field.
    20012002 *
    20022003 * @access private
     
    20082009
    20092010/**
    2010  * Removes the filters that filter footnotes meta field.
     2011 * Removes the filters for footnotes meta field.
    20112012 *
    20122013 * @access private
     
    20182019
    20192020/**
    2020  * Registers the filter of footnotes meta field if the user does not have unfiltered_html capability.
     2021 * Registers the filter of footnotes meta field if the user does not have `unfiltered_html` capability.
    20212022 *
    20222023 * @access private
     
    20312032
    20322033/**
    2033  * Initializes footnotes meta field filters when imported data should be filtered.
    2034  *
    2035  * This filter is the last being executed on force_filtered_html_on_import.
    2036  * If the input of the filter is true it means we are in an import situation and should
    2037  * enable kses, independently of the user capabilities.
    2038  * So in that case we call _wp_footnotes_kses_init_filters;
     2034 * Initializes the filters for footnotes meta field when imported data should be filtered.
     2035 *
     2036 * This filter is the last one being executed on {@see 'force_filtered_html_on_import'}.
     2037 * If the input of the filter is true, it means we are in an import situation and should
     2038 * enable kses, independently of the user capabilities. So in that case we call
     2039 * _wp_footnotes_kses_init_filters().
    20392040 *
    20402041 * @access private
     
    20452046 */
    20462047function _wp_footnotes_force_filtered_html_on_import_filter( $arg ) {
    2047     // force_filtered_html_on_import is true we need to init the global styles kses filters.
     2048    // If `force_filtered_html_on_import` is true, we need to init the global styles kses filters.
    20482049    if ( $arg ) {
    20492050        _wp_footnotes_kses_init_filters();
  • trunk/src/wp-includes/media.php

    r57053 r57120  
    26372637        $post_parent = get_post( $post_parent_id );
    26382638
    2639         // terminate the shortcode execution if user cannot read the post or password-protected
    2640         if (
    2641         ( ! is_post_publicly_viewable( $post_parent->ID ) && ! current_user_can( 'read_post', $post_parent->ID ) )
    2642         || post_password_required( $post_parent ) ) {
     2639        // Terminate the shortcode execution if the user cannot read the post or it is password-protected.
     2640        if ( ! is_post_publicly_viewable( $post_parent->ID ) && ! current_user_can( 'read_post', $post_parent->ID )
     2641            || post_password_required( $post_parent )
     2642        ) {
    26432643            return '';
    26442644        }
     
    29802980        $post_parent = get_post( $id );
    29812981
    2982         // terminate the shortcode execution if user cannot read the post or password-protected
     2982        // Terminate the shortcode execution if the user cannot read the post or it is password-protected.
    29832983        if ( ! current_user_can( 'read_post', $post_parent->ID ) || post_password_required( $post_parent ) ) {
    29842984            return '';
  • trunk/src/wp-includes/rest-api/class-wp-rest-server.php

    r57012 r57120  
    468468
    469469        /**
    470          * Filters whether to send nocache headers on a REST API request.
     470         * Filters whether to send no-cache headers on a REST API request.
    471471         *
    472472         * @since 4.4.0
    473          * @since 6.3.2 Moved the block to catch the filter added on rest_cookie_check_errors() from rest-api.php
     473         * @since 6.3.2 Moved the block to catch the filter added on rest_cookie_check_errors() from wp-includes/rest-api.php.
    474474         *
    475475         * @param bool $rest_send_nocache_headers Whether to send no-cache headers.
     
    477477        $send_no_cache_headers = apply_filters( 'rest_send_nocache_headers', is_user_logged_in() );
    478478
    479         // send no cache headers if the $send_no_cache_headers is true
    480         // OR if the HTTP_X_HTTP_METHOD_OVERRIDE is used but resulted a 4x response code.
     479        /*
     480         * Send no-cache headers if $send_no_cache_headers is true,
     481         * OR if the HTTP_X_HTTP_METHOD_OVERRIDE is used but resulted a 4xx response code.
     482         */
    481483        if ( $send_no_cache_headers || ( true === $method_overridden && strpos( $code, '4' ) === 0 ) ) {
    482484            foreach ( wp_get_nocache_headers() as $header => $header_value ) {
Note: See TracChangeset for help on using the changeset viewer.