Upstream/WordPress
1
0
Fork 0
mirror of https://github.com/WordPress/WordPress.git synced 2024-12-22 09:07:59 +01:00
Code Issues Projects Releases Wiki Activity

Docs: Descriptive improvements and corrections for various docblocks.

Browse Source 
See #53399

Built from https://develop.svn.wordpress.org/trunk@51300


git-svn-id: http://core.svn.wordpress.org/trunk@50909 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
John Blackbourn 2021-07-01 21:12:58 +00:00
parent 9146628ae1
commit ea60cd8191
19 changed files with 123 additions and 80 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

71
wp-admin/includes/file.php
View File

@ -733,9 +733,16 @@ function validate_file_to_edit( $file, $allowed_files = array() ) {
*
* @see wp_handle_upload_error
*
* @param string[] $file Reference to a single element of `$_FILES`.
* Call the function once for each uploaded file.
* @param array|false $overrides {
* @param array $file {
* Reference to a single element from `$_FILES`. Call the function once for each uploaded file.
*
* @type string $name The original name of the file on the client machine.
* @type string $type The mime type of the file, if the browser provided this information.
* @type string $tmp_name The temporary filename of the file in which the uploaded file was stored on the server.
* @type int $size The size, in bytes, of the uploaded file.
* @type int $error The error code associated with this file upload.
* }
* @param array|false $overrides {
* An array of override parameters for this file, or boolean false if none are provided.
*
* @type callable $upload_error_handler Function to call when there is an error during the upload process.
@ -749,11 +756,17 @@ function validate_file_to_edit( $file, $allowed_files = array() ) {
* @type bool $test_type Whether to test that the mime type of the file is as expected.
* @type string[] $mimes Array of allowed mime types keyed by their file extension regex.
* }
* @param string $time Time formatted in 'yyyy/mm'.
* @param string $action Expected value for `$_POST['action']`.
* @return string[] On success, returns an associative array of file attributes.
* On failure, returns `$overrides['upload_error_handler']( &$file, $message )`
* or `array( 'error' => $message )`.
* @param string $time Time formatted in 'yyyy/mm'.
* @param string $action Expected value for `$_POST['action']`.
* @return array {
* On success, returns an associative array of file attributes.
* On failure, returns `$overrides['upload_error_handler']( &$file, $message )`
* or `array( 'error' => $message )`.
*
* @type string $file Filename of the newly-uploaded file.
* @type string $url URL of the newly-uploaded file.
* @type string $type Mime type of the newly-uploaded file.
* }
*/
function _wp_handle_upload( &$file, $overrides, $time, $action ) {
// The default error handler.
@ -776,7 +789,15 @@ function _wp_handle_upload( &$file, $overrides, $time, $action ) {
* @since 2.9.0 as 'wp_handle_upload_prefilter'.
* @since 4.0.0 Converted to a dynamic hook with `$action`.
*
* @param string[] $file An array of data for the file. Reference to a single element of `$_FILES`.
* @param array $file {
* Reference to a single element from `$_FILES`.
*
* @type string $name The original name of the file on the client machine.
* @type string $type The mime type of the file, if the browser provided this information.
* @type string $tmp_name The temporary filename of the file in which the uploaded file was stored on the server.
* @type int $size The size, in bytes, of the uploaded file.
* @type int $error The error code associated with this file upload.
* }
*/
$file = apply_filters( "{$action}_prefilter", $file );
@ -794,7 +815,15 @@ function _wp_handle_upload( &$file, $overrides, $time, $action ) {
*
* @param array|false $overrides An array of override parameters for this file. Boolean false if none are
* provided. @see _wp_handle_upload().
* @param string[] $file An array of data for the file. Reference to a single element of `$_FILES`.
* @param array $file {
* Reference to a single element from `$_FILES`.
*
* @type string $name The original name of the file on the client machine.
* @type string $type The mime type of the file, if the browser provided this information.
* @type string $tmp_name The temporary filename of the file in which the uploaded file was stored on the server.
* @type int $size The size, in bytes, of the uploaded file.
* @type int $error The error code associated with this file upload.
* }
*/
$overrides = apply_filters( "{$action}_overrides", $overrides, $file );
@ -935,7 +964,15 @@ function _wp_handle_upload( &$file, $overrides, $time, $action ) {
* @since 4.9.0
*
* @param mixed $move_new_file If null (default) move the file after the upload.
* @param string[] $file An array of data for a single file.
* @param array $file {
* Reference to a single element from `$_FILES`.
*
* @type string $name The original name of the file on the client machine.
* @type string $type The mime type of the file, if the browser provided this information.
* @type string $tmp_name The temporary filename of the file in which the uploaded file was stored on the server.
* @type int $size The size, in bytes, of the uploaded file.
* @type int $error The error code associated with this file upload.
* }
* @param string $new_file Filename of the newly-uploaded file.
* @param string $type Mime type of the newly-uploaded file.
*/
@ -1017,12 +1054,12 @@ function _wp_handle_upload( &$file, $overrides, $time, $action ) {
*
* @param array $file Reference to a single element of `$_FILES`.
* Call the function once for each uploaded file.
* See _wp_handle_upload() for accepted values.
* @param array|false $overrides Optional. An associative array of names => values
* to override default variables. Default false.
* See _wp_handle_upload() for accepted values.
* @param string $time Optional. Time formatted in 'yyyy/mm'. Default null.
* @return array On success, returns an associative array of file attributes.
* On failure, returns `$overrides['upload_error_handler']( &$file, $message )`
* or `array( 'error' => $message )`.
* @return array See _wp_handle_upload() for return value.
*/
function wp_handle_upload( &$file, $overrides = false, $time = null ) {
/*
@ -1048,12 +1085,12 @@ function wp_handle_upload( &$file, $overrides = false, $time = null ) {
*
* @param array $file Reference to a single element of `$_FILES`.
* Call the function once for each uploaded file.
* See _wp_handle_upload() for accepted values.
* @param array|false $overrides Optional. An associative array of names => values
* to override default variables. Default false.
* See _wp_handle_upload() for accepted values.
* @param string $time Optional. Time formatted in 'yyyy/mm'. Default null.
* @return array On success, returns an associative array of file attributes.
* On failure, returns `$overrides['upload_error_handler']( &$file, $message )`
* or `array( 'error' => $message )`.
* @return array See _wp_handle_upload() for return value.
*/
function wp_handle_sideload( &$file, $overrides = false, $time = null ) {
/*

16
wp-includes/block-supports/elements.php
View File

@ -12,9 +12,9 @@
* @since 5.8.0
* @access private
*
* @param string $block_content Rendered block content.
* @param array $block Block object.
* @return string Filtered block content.
* @param string $block_content Rendered block content.
* @param array $block Block object.
* @return string Filtered block content.
*/
function wp_render_elements_support( $block_content, $block ) {
$link_color = null;
@ -23,11 +23,11 @@ function wp_render_elements_support( $block_content, $block ) {
}
/*
* For now we only care about link color.
* This code in the future when we have a public API
* should take advantage of WP_Theme_JSON::compute_style_properties
* and work for any element and style.
*/
* For now we only care about link color.
* This code in the future when we have a public API
* should take advantage of WP_Theme_JSON::compute_style_properties
* and work for any element and style.
*/
if ( null === $link_color ) {
return $block_content;
}

6
wp-includes/block-supports/layout.php
View File

@ -35,9 +35,9 @@ function wp_register_layout_support( $block_type ) {
* @since 5.8.0
* @access private
*
* @param string $block_content Rendered block content.
* @param array $block Block object.
* @return string Filtered block content.
* @param string $block_content Rendered block content.
* @param array $block Block object.
* @return string Filtered block content.
*/
function wp_render_layout_support_flag( $block_content, $block ) {
$block_type = WP_Block_Type_Registry::get_instance()->get_registered( $block['blockName'] );

5
wp-includes/block-template-utils.php
View File

@ -103,9 +103,8 @@ function get_block_templates( $query = array(), $template_type = 'wp_template' )
*
* @since 5.8.0
*
* @param string $id Template unique identifier (example: theme_slug//template_slug).
* @param string $template_type wp_template.
*
* @param string $id Template unique identifier (example: theme_slug//template_slug).
* @param string $template_type Optional. The template type (post type). Default 'wp_template'.
* @return WP_Block_Template|null Template.
*/
function get_block_template( $id, $template_type = 'wp_template' ) {

2
wp-includes/class-http.php
View File

@ -110,7 +110,7 @@ class WP_Http {
* Some transports technically allow others, but should not be
* assumed. Default 'GET'.
* @type float $timeout How long the connection should stay open in seconds. Default 5.
* @type int $redirection Number of allowed redirects. Not supported by all transports.
* @type int $redirection Number of allowed redirects. Not supported by all transports
* Default 5.
* @type string $httpversion Version of the HTTP protocol to use. Accepts '1.0' and '1.1'.
* Default '1.0'.

2
wp-includes/class-wp-http-requests-hooks.php
View File

@ -63,7 +63,7 @@ class WP_HTTP_Requests_Hooks extends Requests_Hooks {
*
* This action maps Requests internal hook to a native WordPress action.
*
* @see https://github.com/rmccue/Requests/blob/master/docs/hooks.md
* @see https://github.com/WordPress/Requests/blob/master/docs/hooks.md
*
* @since 4.7.0
*

20
wp-includes/class-wp-query.php
View File

@ -18,7 +18,7 @@
class WP_Query {
/**
* Query vars set by the user.
* Query vars set by the user
*
* @since 1.5.0
* @var array
@ -26,7 +26,7 @@ class WP_Query {
public $query;
/**
* Query vars, after parsing.
* Query vars, after parsing
*
* @since 1.5.0
* @var array
@ -34,7 +34,7 @@ class WP_Query {
public $query_vars = array();
/**
* Taxonomy query, as passed to get_tax_sql().
* Taxonomy query, as passed to get_tax_sql()
*
* @since 3.1.0
* @var WP_Tax_Query A taxonomy query instance.
@ -42,7 +42,7 @@ class WP_Query {
public $tax_query;
/**
* Metadata query container.
* Metadata query container
*
* @since 3.2.0
* @var WP_Meta_Query A meta query instance.
@ -50,7 +50,7 @@ class WP_Query {
public $meta_query = false;
/**
* Date query container.
* Date query container
*
* @since 3.7.0
* @var WP_Date_Query A date query instance.
@ -92,7 +92,7 @@ class WP_Query {
public $posts;
/**
* The number of posts for the current query.
* The amount of posts for the current query.
*
* @since 1.5.0
* @var int
@ -135,7 +135,7 @@ class WP_Query {
public $comments;
/**
* The number of comments for the posts.
* The amount of comments for the posts.
*
* @since 2.2.0
* @var int
@ -159,7 +159,7 @@ class WP_Query {
public $comment;
/**
* The number of found posts for the current query.
* The amount of found posts for the current query.
*
* If limit clause was not used, equals $post_count.
*
@ -169,7 +169,7 @@ class WP_Query {
public $found_posts = 0;
/**
* The number of pages.
* The amount of pages.
*
* @since 2.1.0
* @var int
@ -177,7 +177,7 @@ class WP_Query {
public $max_num_pages = 0;
/**
* The number of comment pages.
* The amount of comment pages.
*
* @since 2.7.0
* @var int

43
wp-includes/class-wp-term-query.php
View File

@ -92,23 +92,22 @@ class WP_Term_Query {
* @param string|array $query {
* Optional. Array or query string of term query parameters. Default empty.
*
* @type string|array $taxonomy Taxonomy name, or array of taxonomies, to which results should
* @type string|array $taxonomy Taxonomy name, or array of taxonomy names, to which results should
* be limited.
* @type int|int[] $object_ids Object ID, or array of object IDs. Results will be
* @type int|int[] $object_ids Optional. Object ID, or array of object IDs. Results will be
* limited to terms associated with these objects.
* @type string $orderby Field(s) to order terms by. Accepts:
* * Term fields ('name', 'slug', 'term_group', 'term_id', 'id',
* * term fields ('name', 'slug', 'term_group', 'term_id', 'id',
* 'description', 'parent', 'term_order'). Unless `$object_ids`
* is not empty, 'term_order' is treated the same as 'term_id'.
* * 'count' to use the number of objects associated with the term.
* * 'include' to match the 'order' of the `$include` param.
* * 'slug__in' to match the 'order' of the `$slug` param.
* * 'meta_value'
* * 'meta_value_num'.
* * The value of `$meta_key`.
* * The array keys of `$meta_query`.
* * 'include' to match the 'order' of the $include param.
* * 'slug__in' to match the 'order' of the $slug param.
* * 'meta_value', 'meta_value_num'.
* the value of `$meta_key`.
* the array keys of `$meta_query`.
* * 'none' to omit the ORDER BY clause.
* Default 'name'.
* Defaults to 'name'.
* @type string $order Whether to order terms in ascending or descending order.
* Accepts 'ASC' (ascending) or 'DESC' (descending).
* Default 'ASC'.
@ -117,14 +116,14 @@ class WP_Term_Query {
* @type int[]|string $include Array or comma/space-separated string of term IDs to include.
* Default empty array.
* @type int[]|string $exclude Array or comma/space-separated string of term IDs to exclude.
* If `$include` is non-empty, `$exclude` is ignored.
* If $include is non-empty, $exclude is ignored.
* Default empty array.
* @type int[]|string $exclude_tree Array or comma/space-separated string of term IDs to exclude
* along with all of their descendant terms. If `$include` is
* non-empty, `$exclude_tree` is ignored. Default empty array.
* along with all of their descendant terms. If $include is
* non-empty, $exclude_tree is ignored. Default empty array.
* @type int|string $number Maximum number of terms to return. Accepts ''|0 (all) or any
* positive number. Default ''|0 (all). Note that $number may
* not return accurate results when coupled with `$object_ids`.
* not return accurate results when coupled with $object_ids.
* See #41796 for details.
* @type int $offset The number by which to offset the terms query. Default empty.
* @type string $fields Term fields to query for. Accepts:
@ -146,14 +145,14 @@ class WP_Term_Query {
* Default 'all'.
* @type bool $count Whether to return a term count. If true, will take precedence
* over `$fields`. Default false.
* @type string|array $name Name or array of names to return term(s) for.
* @type string|array $name Optional. Name or array of names to return term(s) for.
* Default empty.
* @type string|array $slug Slug or array of slugs to return term(s) for.
* @type string|array $slug Optional. Slug or array of slugs to return term(s) for.
* Default empty.
* @type int|int[] $term_taxonomy_id Term taxonomy ID, or array of term taxonomy IDs,
* @type int|int[] $term_taxonomy_id Optional. Term taxonomy ID, or array of term taxonomy IDs,
* to match when querying terms.
* @type bool $hierarchical Whether to include terms that have non-empty descendants
* (even if `$hide_empty` is set to true). Default true.
* (even if $hide_empty is set to true). Default true.
* @type string $search Search criteria to match terms. Will be SQL-formatted with
* wildcards before and after. Default empty.
* @type string $name__like Retrieve terms with criteria by which a term is LIKE
@ -164,8 +163,8 @@ class WP_Term_Query {
* quantity of each term's "count" object variable.
* Default false.
* @type string $get Whether to return terms regardless of ancestry or whether the
* terms are empty. Accepts 'all' or '' (disabled).
* Default ''.
* terms are empty. Accepts 'all' or empty (disabled).
* Default empty.
* @type int $child_of Term ID to retrieve child terms of. If multiple taxonomies
* are passed, `$child_of` is ignored. Default 0.
* @type int $parent Parent term ID to retrieve direct-child terms of.
@ -174,9 +173,9 @@ class WP_Term_Query {
* This parameter has no effect on non-hierarchical taxonomies.
* Default false.
* @type string $cache_domain Unique cache key to be produced when this query is stored in
* an object cache. Default 'core'.
* an object cache. Default is 'core'.
* @type bool $update_term_meta_cache Whether to prime meta caches for matched terms. Default true.
* @type array $meta_query Meta query clauses to limit retrieved terms by.
* @type array $meta_query Optional. Meta query clauses to limit retrieved terms by.
* See `WP_Meta_Query`. Default empty.
* @type string $meta_key Limit terms to those matching a specific metadata key.
* Can be used in conjunction with `$meta_value`. Default empty.

4
wp-includes/comment-template.php
View File

@ -262,7 +262,7 @@ function comment_author_link( $comment_ID = 0 ) {
*
* @param int|WP_Comment $comment_ID Optional. WP_Comment or the ID of the comment for which to get the author's IP address.
* Default current comment.
* @return string Comment author's IP address.
* @return string Comment author's IP address, or an empty string if it's not available.
*/
function get_comment_author_IP( $comment_ID = 0 ) { // phpcs:ignore WordPress.NamingConventions.ValidFunctionName.FunctionNameInvalid
$comment = get_comment( $comment_ID );
@ -273,7 +273,7 @@ function get_comment_author_IP( $comment_ID = 0 ) { // phpcs:ignore WordPress.Na
* @since 1.5.0
* @since 4.1.0 The `$comment_ID` and `$comment` parameters were added.
*
* @param string $comment_author_IP The comment author's IP address.
* @param string $comment_author_IP The comment author's IP address, or an empty string if it's not available.
* @param int $comment_ID The comment ID.
* @param WP_Comment $comment The comment object.
*/

7
wp-includes/customize/class-wp-customize-date-time-control.php
View File

@ -214,7 +214,12 @@ class WP_Customize_Date_Time_Control extends WP_Customize_Control {
*
* @since 4.9.0
*
* @return array abbr and description.
* @return array {
* Timezone info. All properties are optional.
*
* @type string $abbr Timezone abbreviation, eg. PST or CEST.
* @type string $description Human-readable timezone description as HTML.
* }
*/
public function get_timezone_info() {
$tz_string = get_option( 'timezone_string' );

2
wp-includes/functions.php
View File

@ -218,6 +218,8 @@ function date_i18n( $format, $timestamp_with_offset = false, $gmt = false ) {
*
* @since 5.3.0
*
* @global WP_Locale $wp_locale WordPress date and time locale object.
*
* @param string $format PHP date format.
* @param int $timestamp Optional. Unix timestamp. Defaults to current time.
* @param DateTimeZone $timezone Optional. Timezone to output result in. Defaults to timezone

4
wp-includes/kses.php
View File

@ -854,7 +854,7 @@ function wp_kses_allowed_html( $context = '' ) {
if ( is_array( $context ) ) {
/**
* Filters the HTML that is allowed for a given context.
* Filters the HTML tags that are allowed for a given context.
*
* @since 3.5.0
*
@ -1040,7 +1040,7 @@ function wp_kses_uri_attributes() {
* or a context name such as 'post'.
* @global string[] $pass_allowed_protocols Array of allowed URL protocols.
*
* @param array $matches preg_replace regexp matches
* @param array $match preg_replace regexp matches
* @return string
*/
function _wp_kses_split_callback( $match ) {

2
wp-includes/load.php
View File

@ -675,7 +675,7 @@ function wp_start_object_cache() {
* @since 5.8.0
*
* @param bool $enable_object_cache Whether to enable loading object-cache.php (if present).
* Default true.
* Default true.
*/
if ( $first_init && apply_filters( 'enable_loading_object_cache_dropin', true ) ) {
if ( ! function_exists( 'wp_cache_init' ) ) {

2
wp-includes/nav-menu.php
View File

@ -159,7 +159,7 @@ function get_registered_nav_menus() {
*
* @since 3.0.0
*
* @return int[] Associative array of registered navigation menu IDs keyed by their
* @return int[] Associative array of egistered navigation menu IDs keyed by their
* location name. If none are registered, an empty array.
*/
function get_nav_menu_locations() {

3
wp-includes/pluggable.php
View File

@ -2785,7 +2785,8 @@ if ( ! function_exists( 'get_avatar' ) ) :
* @param int $size Square avatar width and height in pixels to retrieve.
* @param string $default URL for the default image or a default type. Accepts '404', 'retro', 'monsterid',
* 'wavatar', 'indenticon', 'mystery', 'mm', 'mysteryman', 'blank', or 'gravatar_default'.
* @param string $alt Alternative text to use in the avatar image tag.
* Default is the value of the 'avatar_default' option, with a fallback of 'mystery'.
* @param string $alt Alternative text to use in the avatar image tag. Default empty.
* @param array $args Arguments passed to get_avatar_data(), after processing.
*/
return apply_filters( 'get_avatar', $avatar, $id_or_email, $args['size'], $args['default'], $args['alt'], $args );

8
wp-includes/post.php
View File

@ -1391,7 +1391,7 @@ function get_post_types( $args = array(), $output = 'names', $operator = 'and' )
* @type bool $public Whether a post type is intended for use publicly either via
* the admin interface or by front-end users. While the default
* settings of $exclude_from_search, $publicly_queryable, $show_ui,
* and $show_in_nav_menus are inherited from $public, each does not
* and $show_in_nav_menus are inherited from public, each does not
* rely on this relationship and controls a very specific intention.
* Default false.
* @type bool $hierarchical Whether the post type is hierarchical (e.g. page). Default false.
@ -1417,11 +1417,11 @@ function get_post_types( $args = array(), $output = 'names', $operator = 'and' )
* of $show_in_menu.
* @type bool $show_in_rest Whether to include the post type in the REST API. Set this to true
* for the post type to be available in the block editor.
* @type string $rest_base To change the base URL of REST API route. Default is $post_type.
* @type string $rest_controller_class REST API controller class name. Default is 'WP_REST_Posts_Controller'.
* @type string $rest_base To change the base url of REST API route. Default is $post_type.
* @type string $rest_controller_class REST API Controller class name. Default is 'WP_REST_Posts_Controller'.
* @type int $menu_position The position in the menu order the post type should appear. To work,
* $show_in_menu must be true. Default null (at the bottom).
* @type string $menu_icon The URL to the icon to be used for this menu. Pass a base64-encoded
* @type string $menu_icon The url to the icon to be used for this menu. Pass a base64-encoded
* SVG using a data URI, which will be colored to match the color scheme
* -- this should begin with 'data:image/svg+xml;base64,'. Pass the name
* of a Dashicons helper class to use a font icon, e.g.

2
wp-includes/user.php
View File

@ -1749,7 +1749,7 @@ function validate_username( $username ) {
* @type string $admin_color Admin color scheme for the user. Default 'fresh'.
* @type bool $use_ssl Whether the user should always access the admin over
* https. Default false.
* @type string $user_registered Date the user registered. Format is 'Y-m-d H:i:s'.
* @type string $user_registered Date the user registered in UTC. Format is 'Y-m-d H:i:s'.
* @type string $user_activation_key Password reset key. Default empty.
* @type bool $spam Multisite only. Whether the user is marked as spam.
* Default false.

2
wp-includes/version.php
View File

@ -13,7 +13,7 @@
*
* @global string $wp_version
*/
$wp_version = '5.9-alpha-51299';
$wp_version = '5.9-alpha-51300';
/**
* Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.

2
wp-includes/widgets.php
View File

@ -1832,7 +1832,7 @@ function wp_setup_widgets_block_editor() {
*/
function wp_use_widgets_block_editor() {
/**
* Filters whether or not to use the block editor to manage widgets.
* Filters whether to use the block editor to manage widgets.
*
* @since 5.8.0
*