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.
Built from https://develop.svn.wordpress.org/trunk@57120


git-svn-id: http://core.svn.wordpress.org/trunk@56631 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
Sergey Biryukov 2023-11-17 13:29:26 +00:00
parent 382c01d848
commit d7a1816bf1
7 changed files with 34 additions and 31 deletions

View File

@ -662,7 +662,7 @@ class WP_Comments_List_Table extends WP_List_Table {
current_user_can( 'read_post', $comment->comment_post_ID )
)
) {
// The user has access to the post
// The user has access to the post and thus can see comments.
} else {
return false;
}

View File

@ -860,7 +860,7 @@ class WP_List_Table {
current_user_can( 'read_post', $post_id )
)
) {
// 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;
}

View File

@ -638,7 +638,7 @@ Please click the following link to activate your user account:
*
* @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 {
* The array of request data. All arguments are optional and may be empty.
@ -700,12 +700,11 @@ function wp_is_authorize_application_password_request_valid( $request, $user ) {
}
/**
* 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.
*/
function wp_is_authorize_application_redirect_url_valid( $url ) {
@ -731,13 +730,14 @@ function wp_is_authorize_application_redirect_url_valid( $url ) {
* @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 );
$host = wp_parse_url( $url, PHP_URL_HOST );
$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(
'invalid_redirect_url_format',

View File

@ -1971,13 +1971,14 @@ function get_comments_pagination_arrow( $block, $pagination_type = 'next' ) {
/**
* Strips all HTML from the content of footnotes, and sanitizes the ID.
*
* This function expects slashed data on the footnotes content.
*
* @access private
* @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 ) {
$footnotes_decoded = json_decode( $footnotes, true );
@ -1997,7 +1998,7 @@ function _wp_filter_post_meta_footnotes( $footnotes ) {
}
/**
* Adds the filters to filter footnotes meta field.
* Adds the filters for footnotes meta field.
*
* @access private
* @since 6.3.2
@ -2007,7 +2008,7 @@ function _wp_footnotes_kses_init_filters() {
}
/**
* Removes the filters that filter footnotes meta field.
* Removes the filters for footnotes meta field.
*
* @access private
* @since 6.3.2
@ -2017,7 +2018,7 @@ function _wp_footnotes_remove_filters() {
}
/**
* 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
* @since 6.3.2
@ -2030,12 +2031,12 @@ function _wp_footnotes_kses_init() {
}
/**
* Initializes footnotes meta field filters when imported data should be filtered.
* Initializes the filters for footnotes meta field 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;
* 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
* @since 6.3.2
@ -2044,7 +2045,7 @@ function _wp_footnotes_kses_init() {
* @return string Input argument of the filter.
*/
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();
}

View File

@ -2636,10 +2636,10 @@ function gallery_shortcode( $attr ) {
if ( ! empty( $post_parent_id ) ) {
$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 '';
}
}
@ -2979,7 +2979,7 @@ function wp_playlist_shortcode( $attr ) {
if ( ! empty( $args['post_parent'] ) ) {
$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 '';
}

View File

@ -467,17 +467,19 @@ class WP_REST_Server {
$this->set_status( $code );
/**
* 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.
*/
$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 ) {
if ( empty( $header_value ) ) {

View File

@ -16,7 +16,7 @@
*
* @global string $wp_version
*/
$wp_version = '6.5-alpha-57118';
$wp_version = '6.5-alpha-57120';
/**
* Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.