WordPress-C
/
WordPress
mirror of https://github.com/WordPress/WordPress.git
1
0
Fork 0
Code Issues Packages 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. * @type int|string $category_parent Category parent ID. Default empty.
* } * }
* @param bool $wp_error Optional. Default false. * @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, * @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. * depending on param `$wp_error`.
*/ */
function wp_insert_category( $catarr, $wp_error = false ) { function wp_insert_category( $catarr, $wp_error = false ) {
$cat_defaults = array( $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 * @since 5.5.0
*/ */
final class WP_Block_Patterns_Registry { final class WP_Block_Patterns_Registry {
/** /**
* Registered patterns array. * Registered block patterns array.
* *
* @since 5.5.0 * @since 5.5.0
* @var array * @var array
@ -30,29 +30,29 @@ final class WP_Block_Patterns_Registry {
private static $instance = null; private static $instance = null;
/** /**
* Registers a pattern. * Registers a block pattern.
* *
* @since 5.5.0 * @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 { * @param array $pattern_properties {
* List of properties for the block pattern. * List of properties for the block pattern.
* *
* @type string $title Required. A human-readable title for the pattern. * @type string $title Required. A human-readable title for the pattern.
* @type string $content Required. Block HTML markup 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 * inserter. A description is optional, but is strongly
* encouraged when the title does not fully describe what the * encouraged when the title does not fully describe what the
* pattern does. The description will help users discover the * pattern does. The description will help users discover the
* pattern while searching. Optional. * pattern while searching.
* @type int $viewportWidth The intended width of the pattern to allow for a scaled * @type int $viewportWidth Optional. The intended width of the pattern to allow for a scaled
* preview within the pattern inserter. Optional. * preview within the pattern inserter.
* @type array $categories A list of registered pattern categories used to group block * @type array $categories Optional. A list of registered pattern categories used to group block
* patterns. Block patterns can be shown on multiple categories. * patterns. Block patterns can be shown on multiple categories.
* A category must be registered separately in order to be used * A category must be registered separately in order to be used
* here. Optional. * here.
* @type array $keywords A list of aliases or keywords that help users discover the * @type array $keywords Optional. A list of aliases or keywords that help users discover the
* pattern while searching. Optional. * pattern while searching.
* } * }
* @return bool True if the pattern was registered with success and false otherwise. * @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 * @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. * @return bool True if the pattern was unregistered with success and false otherwise.
*/ */
public function unregister( $pattern_name ) { 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 * @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. * @return array Registered pattern properties.
*/ */
public function get_registered( $pattern_name ) { 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 * @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. * and per style.
*/ */
public function get_all_registered() { 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 * @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. * @return bool True if the pattern is registered, false otherwise.
*/ */
public function is_registered( $pattern_name ) { 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 * @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. * @param array $pattern_properties List of properties for the block pattern.
* See WP_Block_Patterns_Registry::register() for accepted arguments. * See WP_Block_Patterns_Registry::register() for accepted arguments.
* @return bool True if the pattern was registered with success and false otherwise. * @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 ) { function register_block_pattern( $pattern_name, $pattern_properties ) {
return WP_Block_Patterns_Registry::get_instance()->register( $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 * @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. * @return bool True if the pattern was unregistered with success and false otherwise.
*/ */
function unregister_block_pattern( $pattern_name ) { 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. * Registered block styles, as `$block_name => $block_style_name => $block_style_properties` multidimensional arrays.
* *
* @since 5.3.0 * @since 5.3.0
* @var array *
* @var array[]
*/ */
private $registered_block_styles = array(); private $registered_block_styles = array();
@ -25,12 +26,13 @@ final class WP_Block_Styles_Registry {
* Container for the main instance of the class. * Container for the main instance of the class.
* *
* @since 5.3.0 * @since 5.3.0
*
* @var WP_Block_Styles_Registry|null * @var WP_Block_Styles_Registry|null
*/ */
private static $instance = null; private static $instance = null;
/** /**
* Registers a block style. * Registers a block style for the given block type.
* *
* @since 5.3.0 * @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_name Block type name including namespace.
* @param string $block_style_name Block style name. * @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 * @since 5.3.0
* *
@ -115,20 +119,19 @@ final class WP_Block_Styles_Registry {
* *
* @since 5.3.0 * @since 5.3.0
* *
* @return array Array of arrays containing the registered block styles properties grouped per block, * @return array[] Array of arrays containing the registered block styles properties grouped by block type.
* and per style.
*/ */
public function get_all_registered() { public function get_all_registered() {
return $this->registered_block_styles; 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 * @since 5.3.0
* *
* @param string $block_name Block type name including namespace. * @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 ) { public function get_registered_styles_for_block( $block_name ) {
if ( isset( $this->registered_block_styles[ $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 * @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 * @since 5.6.0
*/ */
@ -72,7 +72,7 @@ class WP_Block_Supports {
* *
* @since 5.6.0 * @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. * @param array $block_support_config Array containing the properties of the block support.
*/ */
public function register( $block_support_name, $block_support_config ) { public function register( $block_support_name, $block_support_config ) {
@ -88,7 +88,7 @@ class WP_Block_Supports {
* *
* @since 5.6.0 * @since 5.6.0
* *
* @return array Array of HTML attributes. * @return string[] Array of HTML attributes.
*/ */
public function apply_block_supports() { public function apply_block_supports() {
$block_attributes = self::$block_to_render['attrs']; $block_attributes = self::$block_to_render['attrs'];
@ -163,9 +163,8 @@ class WP_Block_Supports {
* *
* @since 5.6.0 * @since 5.6.0
* *
* @param array $extra_attributes Optional. Extra attributes to render on the block wrapper. * @param string[] $extra_attributes Optional. Array of extra attributes to render on the block wrapper.
* * @return string String of HTML attributes.
* @return string String of HTML classes.
*/ */
function get_block_wrapper_attributes( $extra_attributes = array() ) { function get_block_wrapper_attributes( $extra_attributes = array() ) {
$new_attributes = WP_Block_Supports::get_instance()->apply_block_supports(); $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. * Whether a template is, or is based upon, an existing template file.
* *
* @since 5.8.0 * @since 5.8.0
* @var boolean * @var bool
*/ */
public $has_theme_file; public $has_theme_file;
@ -106,7 +106,7 @@ class WP_Block_Template {
* *
* @since 5.9.0 * @since 5.9.0
* *
* @var boolean * @var bool
*/ */
public $is_custom = true; 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 * @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_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 string $primary_id_column ID column for the filtered object in $primary_table.
* @param object $context Optional. The main query object. * @param object $context Optional. The main query object that corresponds to the type, for
* @return array|false { * example a `WP_Query`, `WP_User_Query`, or `WP_Site_Query`.
* Array containing JOIN and WHERE SQL clauses to append to the main 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 $join SQL fragment to append to the main JOIN clause.
* @type string $where SQL fragment to append to the main WHERE 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 * @since 3.1.0
* *
* @param array $sql Array containing the query's JOIN and WHERE clauses. * @param string[] $sql Array containing the query's JOIN and WHERE clauses.
* @param array $queries Array of meta queries. * @param array $queries Array of meta queries.
* @param string $type Type of meta. * @param string $type Type of meta. Possible values include but are not limited
* @param string $primary_table Primary table. * to 'post', 'comment', 'blog', 'term', and 'user'.
* @param string $primary_id_column Primary column ID. * @param string $primary_table Primary table.
* @param object $context The main query object. * @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 ) ); 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 * @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() { function wp_get_ready_cron_jobs() {
/** /**
@ -1124,8 +1124,8 @@ function wp_get_ready_cron_jobs() {
* *
* @since 5.1.0 * @since 5.1.0
* *
* @param null|array $pre Array of ready cron tasks to return instead. Default null * @param null|array[] $pre Array of ready cron tasks to return instead. Default null
* to continue using results from _get_cron_array(). * to continue using results from _get_cron_array().
*/ */
$pre = apply_filters( 'pre_get_ready_cron_jobs', null ); $pre = apply_filters( 'pre_get_ready_cron_jobs', null );
if ( null !== $pre ) { if ( null !== $pre ) {
@ -1164,7 +1164,7 @@ function wp_get_ready_cron_jobs() {
* @since 2.1.0 * @since 2.1.0
* @access private * @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() { function _get_cron_array() {
$cron = get_option( 'cron' ); $cron = get_option( 'cron' );
@ -1190,8 +1190,8 @@ function _get_cron_array() {
* *
* @access private * @access private
* *
* @param array $cron Cron info array from _get_cron_array(). * @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. * @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. * @return bool|WP_Error True if cron array updated. False or WP_Error on failure.
*/ */
function _set_cron_array( $cron, $wp_error = false ) { 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 * @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.8.0
* @since 5.9.0 Renamed `$raw_pattern` to `$item` to match parent class for PHP 8 named parameter support. * @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 ); $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 * @since 5.8.0
* *
* @param WP_REST_Response $response The response object. * @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. * @param WP_REST_Request $request The request object.
*/ */
return apply_filters( 'rest_prepare_block_pattern', $response, $raw_pattern, $request ); 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 * @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 * @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 * @since 5.8.0
* *

2
wp-includes/version.php
View File

@ -16,7 +16,7 @@
* *
* @global string $wp_version * @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. * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.