Upstream
/
WordPress
mirror of https://github.com/WordPress/WordPress.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Docs: Various docblock corrections and improvements. 

See #53399

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


git-svn-id: http://core.svn.wordpress.org/trunk@51828 1a063a9b-81f0-0310-95a4-ce76da25c4cd
This commit is contained in:
John Blackbourn 2021-11-23 21:37:01 +00:00
parent d472b34c89
commit 92f0b0cb48
9 changed files with 76 additions and 68 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
wp-admin/includes/taxonomy.php
View File

@ -115,8 +115,8 @@ function wp_create_categories( $categories, $post_id = '' ) {
* @type int|string $category_parent Category parent ID. Default empty.
* }
* @param bool $wp_error Optional. Default false.
* @return int|object The ID number of the new or updated Category on success. Zero or a WP_Error on failure,
* depending on param $wp_error.
* @return int|WP_Error The ID number of the new or updated Category on success. Zero or a WP_Error on failure,
* depending on param `$wp_error`.
*/
function wp_insert_category( $catarr, $wp_error = false ) {
$cat_defaults = array(

51
wp-includes/class-wp-block-patterns-registry.php
View File

@ -8,13 +8,13 @@
*/
/**
* Class used for interacting with patterns.
* Class used for interacting with block patterns.
*
* @since 5.5.0
*/
final class WP_Block_Patterns_Registry {
/**
* Registered patterns array.
* Registered block patterns array.
*
* @since 5.5.0
* @var array
@ -30,29 +30,29 @@ final class WP_Block_Patterns_Registry {
private static $instance = null;
/**
* Registers a pattern.
* Registers a block pattern.
*
* @since 5.5.0
*
* @param string $pattern_name Pattern name including namespace.
* @param array $pattern_properties {
* @param string $pattern_name Block pattern name including namespace.
* @param array $pattern_properties {
* List of properties for the block pattern.
*
* @type string $title Required. A human-readable title for the pattern.
* @type string $content Required. Block HTML markup for the pattern.
* @type string $description Visually hidden text used to describe the pattern in the
* @type string $description Optional. Visually hidden text used to describe the pattern in the
* inserter. A description is optional, but is strongly
* encouraged when the title does not fully describe what the
* pattern does. The description will help users discover the
* pattern while searching. Optional.
* @type int $viewportWidth The intended width of the pattern to allow for a scaled
* preview within the pattern inserter. Optional.
* @type array $categories A list of registered pattern categories used to group block
* pattern while searching.
* @type int $viewportWidth Optional. The intended width of the pattern to allow for a scaled
* preview within the pattern inserter.
* @type array $categories Optional. A list of registered pattern categories used to group block
* patterns. Block patterns can be shown on multiple categories.
* A category must be registered separately in order to be used
* here. Optional.
* @type array $keywords A list of aliases or keywords that help users discover the
* pattern while searching. Optional.
* here.
* @type array $keywords Optional. A list of aliases or keywords that help users discover the
* pattern while searching.
* }
* @return bool True if the pattern was registered with success and false otherwise.
*/
@ -93,11 +93,11 @@ final class WP_Block_Patterns_Registry {
}
/**
* Unregisters a pattern.
* Unregisters a block pattern.
*
* @since 5.5.0
*
* @param string $pattern_name Pattern name including namespace.
* @param string $pattern_name Block pattern name including namespace.
* @return bool True if the pattern was unregistered with success and false otherwise.
*/
public function unregister( $pattern_name ) {
@ -117,11 +117,11 @@ final class WP_Block_Patterns_Registry {
}
/**
* Retrieves an array containing the properties of a registered pattern.
* Retrieves an array containing the properties of a registered block pattern.
*
* @since 5.5.0
*
* @param string $pattern_name Pattern name including namespace.
* @param string $pattern_name Block pattern name including namespace.
* @return array Registered pattern properties.
*/
public function get_registered( $pattern_name ) {
@ -133,11 +133,11 @@ final class WP_Block_Patterns_Registry {
}
/**
* Retrieves all registered patterns.
* Retrieves all registered block patterns.
*
* @since 5.5.0
*
* @return array Array of arrays containing the registered patterns properties,
* @return array Array of arrays containing the registered block patterns properties,
* and per style.
*/
public function get_all_registered() {
@ -145,11 +145,11 @@ final class WP_Block_Patterns_Registry {
}
/**
* Checks if a pattern is registered.
* Checks if a block pattern is registered.
*
* @since 5.5.0
*
* @param string $pattern_name Pattern name including namespace.
* @param string $pattern_name Block pattern name including namespace.
* @return bool True if the pattern is registered, false otherwise.
*/
public function is_registered( $pattern_name ) {
@ -175,11 +175,11 @@ final class WP_Block_Patterns_Registry {
}
/**
* Registers a new pattern.
* Registers a new block pattern.
*
* @since 5.5.0
*
* @param string $pattern_name Pattern name including namespace.
* @param string $pattern_name Block pattern name including namespace.
* @param array $pattern_properties List of properties for the block pattern.
* See WP_Block_Patterns_Registry::register() for accepted arguments.
* @return bool True if the pattern was registered with success and false otherwise.
@ -187,12 +187,13 @@ final class WP_Block_Patterns_Registry {
function register_block_pattern( $pattern_name, $pattern_properties ) {
return WP_Block_Patterns_Registry::get_instance()->register( $pattern_name, $pattern_properties );
}
/**
* Unregisters a pattern.
* Unregisters a block pattern.
*
* @since 5.5.0
*
* @param string $pattern_name Pattern name including namespace.
* @param string $pattern_name Block pattern name including namespace.
* @return bool True if the pattern was unregistered with success and false otherwise.
*/
function unregister_block_pattern( $pattern_name ) {

21
wp-includes/class-wp-block-styles-registry.php
View File

@ -17,7 +17,8 @@ final class WP_Block_Styles_Registry {
* Registered block styles, as `$block_name => $block_style_name => $block_style_properties` multidimensional arrays.
*
* @since 5.3.0
* @var array
*
* @var array[]
*/
private $registered_block_styles = array();
@ -25,12 +26,13 @@ final class WP_Block_Styles_Registry {
* Container for the main instance of the class.
*
* @since 5.3.0
*
* @var WP_Block_Styles_Registry|null
*/
private static $instance = null;
/**
* Registers a block style.
* Registers a block style for the given block type.
*
* @since 5.3.0
*
@ -71,7 +73,9 @@ final class WP_Block_Styles_Registry {
}
/**
* Unregisters a block style.
* Unregisters a block style of the given block type.
*
* @since 5.3.0
*
* @param string $block_name Block type name including namespace.
* @param string $block_style_name Block style name.
@ -94,7 +98,7 @@ final class WP_Block_Styles_Registry {
}
/**
* Retrieves an array containing the properties of a registered block style.
* Retrieves the properties of a registered block style for the given block type.
*
* @since 5.3.0
*
@ -115,20 +119,19 @@ final class WP_Block_Styles_Registry {
*
* @since 5.3.0
*
* @return array Array of arrays containing the registered block styles properties grouped per block,
* and per style.
* @return array[] Array of arrays containing the registered block styles properties grouped by block type.
*/
public function get_all_registered() {
return $this->registered_block_styles;
}
/**
* Retrieves registered block styles for a specific block.
* Retrieves registered block styles for a specific block type.
*
* @since 5.3.0
*
* @param string $block_name Block type name including namespace.
* @return array Array whose keys are block style names and whose value are block style properties.
* @return array[] Array whose keys are block style names and whose values are block style properties.
*/
public function get_registered_styles_for_block( $block_name ) {
if ( isset( $this->registered_block_styles[ $block_name ] ) ) {
@ -138,7 +141,7 @@ final class WP_Block_Styles_Registry {
}
/**
* Checks if a block style is registered.
* Checks if a block style is registered for the given block type.
*
* @since 5.3.0
*

11
wp-includes/class-wp-block-supports.php
View File

@ -58,7 +58,7 @@ class WP_Block_Supports {
}
/**
* Initializes the block supports. It registes the block supports block attributes.
* Initializes the block supports. It registers the block supports block attributes.
*
* @since 5.6.0
*/
@ -72,7 +72,7 @@ class WP_Block_Supports {
*
* @since 5.6.0
*
* @param string $block_support_name Block support name.
* @param string $block_support_name Block support name.
* @param array $block_support_config Array containing the properties of the block support.
*/
public function register( $block_support_name, $block_support_config ) {
@ -88,7 +88,7 @@ class WP_Block_Supports {
*
* @since 5.6.0
*
* @return array Array of HTML attributes.
* @return string[] Array of HTML attributes.
*/
public function apply_block_supports() {
$block_attributes = self::$block_to_render['attrs'];
@ -163,9 +163,8 @@ class WP_Block_Supports {
*
* @since 5.6.0
*
* @param array $extra_attributes Optional. Extra attributes to render on the block wrapper.
*
* @return string String of HTML classes.
* @param string[] $extra_attributes Optional. Array of extra attributes to render on the block wrapper.
* @return string String of HTML attributes.
*/
function get_block_wrapper_attributes( $extra_attributes = array() ) {
$new_attributes = WP_Block_Supports::get_instance()->apply_block_supports();

4
wp-includes/class-wp-block-template.php
View File

@ -97,7 +97,7 @@ class WP_Block_Template {
* Whether a template is, or is based upon, an existing template file.
*
* @since 5.8.0
* @var boolean
* @var bool
*/
public $has_theme_file;
@ -106,7 +106,7 @@ class WP_Block_Template {
*
* @since 5.9.0
*
* @var boolean
* @var bool
*/
public $is_custom = true;
}

25
wp-includes/class-wp-meta-query.php
View File

@ -338,12 +338,15 @@ class WP_Meta_Query {
*
* @since 3.2.0
*
* @param string $type Type of meta, eg 'user', 'post'.
* @param string $type Type of meta. Possible values include but are not limited
* to 'post', 'comment', 'blog', 'term', and 'user'.
* @param string $primary_table Database table where the object being filtered is stored (eg wp_users).
* @param string $primary_id_column ID column for the filtered object in $primary_table.
* @param object $context Optional. The main query object.
* @return array|false {
* Array containing JOIN and WHERE SQL clauses to append to the main query.
* @param object $context Optional. The main query object that corresponds to the type, for
* example a `WP_Query`, `WP_User_Query`, or `WP_Site_Query`.
* @return string[]|false {
* Array containing JOIN and WHERE SQL clauses to append to the main query,
* or false if no table exists for the requested meta type.
*
* @type string $join SQL fragment to append to the main JOIN clause.
* @type string $where SQL fragment to append to the main WHERE clause.
@ -378,12 +381,14 @@ class WP_Meta_Query {
*
* @since 3.1.0
*
* @param array $sql Array containing the query's JOIN and WHERE clauses.
* @param array $queries Array of meta queries.
* @param string $type Type of meta.
* @param string $primary_table Primary table.
* @param string $primary_id_column Primary column ID.
* @param object $context The main query object.
* @param string[] $sql Array containing the query's JOIN and WHERE clauses.
* @param array $queries Array of meta queries.
* @param string $type Type of meta. Possible values include but are not limited
* to 'post', 'comment', 'blog', 'term', and 'user'.
* @param string $primary_table Primary table.
* @param string $primary_id_column Primary column ID.
* @param object $context The main query object that corresponds to the type, for
* example a `WP_Query`, `WP_User_Query`, or `WP_Site_Query`.
*/
return apply_filters_ref_array( 'get_meta_sql', array( $sql, $this->queries, $type, $primary_table, $primary_id_column, $context ) );
}

12
wp-includes/cron.php
View File

@ -1113,7 +1113,7 @@ function wp_get_schedule( $hook, $args = array() ) {
*
* @since 5.1.0
*
* @return array Cron jobs ready to be run.
* @return array[] Array of cron job arrays ready to be run.
*/
function wp_get_ready_cron_jobs() {
/**
@ -1124,8 +1124,8 @@ function wp_get_ready_cron_jobs() {
*
* @since 5.1.0
*
* @param null|array $pre Array of ready cron tasks to return instead. Default null
* to continue using results from _get_cron_array().
* @param null|array[] $pre Array of ready cron tasks to return instead. Default null
* to continue using results from _get_cron_array().
*/
$pre = apply_filters( 'pre_get_ready_cron_jobs', null );
if ( null !== $pre ) {
@ -1164,7 +1164,7 @@ function wp_get_ready_cron_jobs() {
* @since 2.1.0
* @access private
*
* @return array|false Cron info array on success, false on failure.
* @return array[]|false Array of cron info arrays on success, false on failure.
*/
function _get_cron_array() {
$cron = get_option( 'cron' );
@ -1190,8 +1190,8 @@ function _get_cron_array() {
*
* @access private
*
* @param array $cron Cron info array from _get_cron_array().
* @param bool $wp_error Optional. Whether to return a WP_Error on failure. Default false.
* @param array[] $cron Array of cron info arrays from _get_cron_array().
* @param bool $wp_error Optional. Whether to return a WP_Error on failure. Default false.
* @return bool|WP_Error True if cron array updated. False or WP_Error on failure.
*/
function _set_cron_array( $cron, $wp_error = false ) {

14
wp-includes/rest-api/endpoints/class-wp-rest-pattern-directory-controller.php
View File

@ -51,7 +51,7 @@ class WP_REST_Pattern_Directory_Controller extends WP_REST_Controller {
}
/**
* Checks whether a given request has permission to view the local pattern directory.
* Checks whether a given request has permission to view the local block pattern directory.
*
* @since 5.8.0
*
@ -196,7 +196,7 @@ class WP_REST_Pattern_Directory_Controller extends WP_REST_Controller {
}
/**
* Prepare a raw pattern before it's output in an API response.
* Prepare a raw block pattern before it gets output in a REST API response.
*
* @since 5.8.0
* @since 5.9.0 Renamed `$raw_pattern` to `$item` to match parent class for PHP 8 named parameter support.
@ -223,19 +223,19 @@ class WP_REST_Pattern_Directory_Controller extends WP_REST_Controller {
$response = new WP_REST_Response( $prepared_pattern );
/**
* Filters the REST API response for a pattern.
* Filters the REST API response for a block pattern.
*
* @since 5.8.0
*
* @param WP_REST_Response $response The response object.
* @param object $raw_pattern The unprepared pattern.
* @param object $raw_pattern The unprepared block pattern.
* @param WP_REST_Request $request The request object.
*/
return apply_filters( 'rest_prepare_block_pattern', $response, $raw_pattern, $request );
}
/**
* Retrieves the pattern's schema, conforming to JSON Schema.
* Retrieves the block pattern's schema, conforming to JSON Schema.
*
* @since 5.8.0
*
@ -307,7 +307,7 @@ class WP_REST_Pattern_Directory_Controller extends WP_REST_Controller {
}
/**
* Retrieves the search params for the patterns collection.
* Retrieves the search parameters for the block pattern's collection.
*
* @since 5.8.0
*
@ -336,7 +336,7 @@ class WP_REST_Pattern_Directory_Controller extends WP_REST_Controller {
);
/**
* Filter collection parameters for the pattern directory controller.
* Filter collection parameters for the block pattern directory controller.
*
* @since 5.8.0
*

2
wp-includes/version.php
View File

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