Make WordPress Core

Changeset 52236


Ignore:
Timestamp:
11/23/2021 09:35:57 PM (3 years ago)
Author:
johnbillion
Message:

Docs: Various docblock corrections and improvements.

See #53399

Location:
trunk/src
Files:
8 edited

Legend:

Unmodified
Added
Removed
  • trunk/src/wp-admin/includes/taxonomy.php

    r51302 r52236  
    116116 * }
    117117 * @param bool  $wp_error Optional. Default false.
    118  * @return int|object The ID number of the new or updated Category on success. Zero or a WP_Error on failure,
    119  *                    depending on param $wp_error.
     118 * @return int|WP_Error The ID number of the new or updated Category on success. Zero or a WP_Error on failure,
     119 *                      depending on param `$wp_error`.
    120120 */
    121121function wp_insert_category( $catarr, $wp_error = false ) {
  • trunk/src/wp-includes/class-wp-block-patterns-registry.php

    r52219 r52236  
    99
    1010/**
    11  * Class used for interacting with patterns.
     11 * Class used for interacting with block patterns.
    1212 *
    1313 * @since 5.5.0
     
    1515final class WP_Block_Patterns_Registry {
    1616    /**
    17      * Registered patterns array.
     17     * Registered block patterns array.
    1818     *
    1919     * @since 5.5.0
     
    3131
    3232    /**
    33      * Registers a pattern.
    34      *
    35      * @since 5.5.0
    36      *
    37      * @param string $pattern_name       Pattern name including namespace.
    38      * @param array $pattern_properties {
     33     * Registers a block pattern.
     34     *
     35     * @since 5.5.0
     36     *
     37     * @param string $pattern_name       Block pattern name including namespace.
     38     * @param array  $pattern_properties {
    3939     *     List of properties for the block pattern.
    4040     *
    4141     *     @type string $title         Required. A human-readable title for the pattern.
    4242     *     @type string $content       Required. Block HTML markup for the pattern.
    43      *     @type string $description   Visually hidden text used to describe the pattern in the
     43     *     @type string $description   Optional. Visually hidden text used to describe the pattern in the
    4444     *                                 inserter. A description is optional, but is strongly
    4545     *                                 encouraged when the title does not fully describe what the
    4646     *                                 pattern does. The description will help users discover the
    47      *                                 pattern while searching. Optional.
    48      *     @type int    $viewportWidth The intended width of the pattern to allow for a scaled
    49      *                                 preview within the pattern inserter. Optional.
    50      *     @type array  $categories    A list of registered pattern categories used to group block
     47     *                                 pattern while searching.
     48     *     @type int    $viewportWidth Optional. The intended width of the pattern to allow for a scaled
     49     *                                 preview within the pattern inserter.
     50     *     @type array  $categories    Optional. A list of registered pattern categories used to group block
    5151     *                                 patterns. Block patterns can be shown on multiple categories.
    5252     *                                 A category must be registered separately in order to be used
    53      *                                 here. Optional.
    54      *     @type array  $keywords      A list of aliases or keywords that help users discover the
    55      *                                 pattern while searching. Optional.
     53     *                                 here.
     54     *     @type array  $keywords      Optional. A list of aliases or keywords that help users discover the
     55     *                                 pattern while searching.
    5656     * }
    5757     * @return bool True if the pattern was registered with success and false otherwise.
     
    9494
    9595    /**
    96      * Unregisters a pattern.
    97      *
    98      * @since 5.5.0
    99      *
    100      * @param string $pattern_name Pattern name including namespace.
     96     * Unregisters a block pattern.
     97     *
     98     * @since 5.5.0
     99     *
     100     * @param string $pattern_name Block pattern name including namespace.
    101101     * @return bool True if the pattern was unregistered with success and false otherwise.
    102102     */
     
    118118
    119119    /**
    120      * Retrieves an array containing the properties of a registered pattern.
    121      *
    122      * @since 5.5.0
    123      *
    124      * @param string $pattern_name Pattern name including namespace.
     120     * Retrieves an array containing the properties of a registered block pattern.
     121     *
     122     * @since 5.5.0
     123     *
     124     * @param string $pattern_name Block pattern name including namespace.
    125125     * @return array Registered pattern properties.
    126126     */
     
    134134
    135135    /**
    136      * Retrieves all registered patterns.
    137      *
    138      * @since 5.5.0
    139      *
    140      * @return array Array of arrays containing the registered patterns properties,
     136     * Retrieves all registered block patterns.
     137     *
     138     * @since 5.5.0
     139     *
     140     * @return array Array of arrays containing the registered block patterns properties,
    141141     *               and per style.
    142142     */
     
    146146
    147147    /**
    148      * Checks if a pattern is registered.
    149      *
    150      * @since 5.5.0
    151      *
    152      * @param string $pattern_name Pattern name including namespace.
     148     * Checks if a block pattern is registered.
     149     *
     150     * @since 5.5.0
     151     *
     152     * @param string $pattern_name Block pattern name including namespace.
    153153     * @return bool True if the pattern is registered, false otherwise.
    154154     */
     
    176176
    177177/**
    178  * Registers a new pattern.
    179  *
    180  * @since 5.5.0
    181  *
    182  * @param string $pattern_name       Pattern name including namespace.
     178 * Registers a new block pattern.
     179 *
     180 * @since 5.5.0
     181 *
     182 * @param string $pattern_name       Block pattern name including namespace.
    183183 * @param array  $pattern_properties List of properties for the block pattern.
    184184 *                                   See WP_Block_Patterns_Registry::register() for accepted arguments.
     
    188188    return WP_Block_Patterns_Registry::get_instance()->register( $pattern_name, $pattern_properties );
    189189}
    190 /**
    191  * Unregisters a pattern.
    192  *
    193  * @since 5.5.0
    194  *
    195  * @param string $pattern_name Pattern name including namespace.
     190
     191/**
     192 * Unregisters a block pattern.
     193 *
     194 * @since 5.5.0
     195 *
     196 * @param string $pattern_name Block pattern name including namespace.
    196197 * @return bool True if the pattern was unregistered with success and false otherwise.
    197198 */
  • trunk/src/wp-includes/class-wp-block-styles-registry.php

    r51154 r52236  
    1818     *
    1919     * @since 5.3.0
    20      * @var array
     20     *
     21     * @var array[]
    2122     */
    2223    private $registered_block_styles = array();
     
    2627     *
    2728     * @since 5.3.0
     29     *
    2830     * @var WP_Block_Styles_Registry|null
    2931     */
     
    3133
    3234    /**
    33      * Registers a block style.
     35     * Registers a block style for the given block type.
    3436     *
    3537     * @since 5.3.0
     
    7274
    7375    /**
    74      * Unregisters a block style.
     76     * Unregisters a block style of the given block type.
     77     *
     78     * @since 5.3.0
    7579     *
    7680     * @param string $block_name       Block type name including namespace.
     
    9599
    96100    /**
    97      * Retrieves an array containing the properties of a registered block style.
     101     * Retrieves the properties of a registered block style for the given block type.
    98102     *
    99103     * @since 5.3.0
     
    116120     * @since 5.3.0
    117121     *
    118      * @return array Array of arrays containing the registered block styles properties grouped per block,
    119      *               and per style.
     122     * @return array[] Array of arrays containing the registered block styles properties grouped by block type.
    120123     */
    121124    public function get_all_registered() {
     
    124127
    125128    /**
    126      * Retrieves registered block styles for a specific block.
     129     * Retrieves registered block styles for a specific block type.
    127130     *
    128131     * @since 5.3.0
    129132     *
    130133     * @param string $block_name Block type name including namespace.
    131      * @return array Array whose keys are block style names and whose value are block style properties.
     134     * @return array[] Array whose keys are block style names and whose values are block style properties.
    132135     */
    133136    public function get_registered_styles_for_block( $block_name ) {
     
    139142
    140143    /**
    141      * Checks if a block style is registered.
     144     * Checks if a block style is registered for the given block type.
    142145     *
    143146     * @since 5.3.0
  • trunk/src/wp-includes/class-wp-block-supports.php

    r51246 r52236  
    5959
    6060    /**
    61      * Initializes the block supports. It registes the block supports block attributes.
     61     * Initializes the block supports. It registers the block supports block attributes.
    6262     *
    6363     * @since 5.6.0
     
    7373     * @since 5.6.0
    7474     *
    75      * @param string $block_support_name Block support name.
     75     * @param string $block_support_name   Block support name.
    7676     * @param array  $block_support_config Array containing the properties of the block support.
    7777     */
     
    8989     * @since 5.6.0
    9090     *
    91      * @return array Array of HTML attributes.
     91     * @return string[] Array of HTML attributes.
    9292     */
    9393    public function apply_block_supports() {
     
    164164 * @since 5.6.0
    165165 *
    166  * @param array $extra_attributes Optional. Extra attributes to render on the block wrapper.
    167  *
    168  * @return string String of HTML classes.
     166 * @param string[] $extra_attributes Optional. Array of extra attributes to render on the block wrapper.
     167 * @return string String of HTML attributes.
    169168 */
    170169function get_block_wrapper_attributes( $extra_attributes = array() ) {
  • trunk/src/wp-includes/class-wp-block-template.php

    r52062 r52236  
    9898     *
    9999     * @since 5.8.0
    100      * @var boolean
     100     * @var bool
    101101     */
    102102    public $has_theme_file;
     
    107107     * @since 5.9.0
    108108     *
    109      * @var boolean
     109     * @var bool
    110110     */
    111111    public $is_custom = true;
  • trunk/src/wp-includes/class-wp-meta-query.php

    r52226 r52236  
    339339     * @since 3.2.0
    340340     *
    341      * @param string $type              Type of meta, eg 'user', 'post'.
     341     * @param string $type              Type of meta. Possible values include but are not limited
     342     *                                  to 'post', 'comment', 'blog', 'term', and 'user'.
    342343     * @param string $primary_table     Database table where the object being filtered is stored (eg wp_users).
    343344     * @param string $primary_id_column ID column for the filtered object in $primary_table.
    344      * @param object $context           Optional. The main query object.
    345      * @return array|false {
    346      *     Array containing JOIN and WHERE SQL clauses to append to the main query.
     345     * @param object $context           Optional. The main query object that corresponds to the type, for
     346     *                                  example a `WP_Query`, `WP_User_Query`, or `WP_Site_Query`.
     347     * @return string[]|false {
     348     *     Array containing JOIN and WHERE SQL clauses to append to the main query,
     349     *     or false if no table exists for the requested meta type.
    347350     *
    348351     *     @type string $join  SQL fragment to append to the main JOIN clause.
     
    379382         * @since 3.1.0
    380383         *
    381          * @param array  $sql               Array containing the query's JOIN and WHERE clauses.
    382          * @param array  $queries           Array of meta queries.
    383          * @param string $type              Type of meta.
    384          * @param string $primary_table     Primary table.
    385          * @param string $primary_id_column Primary column ID.
    386          * @param object $context           The main query object.
     384         * @param string[] $sql               Array containing the query's JOIN and WHERE clauses.
     385         * @param array    $queries           Array of meta queries.
     386         * @param string   $type              Type of meta. Possible values include but are not limited
     387         *                                    to 'post', 'comment', 'blog', 'term', and 'user'.
     388         * @param string   $primary_table     Primary table.
     389         * @param string   $primary_id_column Primary column ID.
     390         * @param object   $context           The main query object that corresponds to the type, for
     391         *                                    example a `WP_Query`, `WP_User_Query`, or `WP_Site_Query`.
    387392         */
    388393        return apply_filters_ref_array( 'get_meta_sql', array( $sql, $this->queries, $type, $primary_table, $primary_id_column, $context ) );
  • trunk/src/wp-includes/cron.php

    r51955 r52236  
    11141114 * @since 5.1.0
    11151115 *
    1116  * @return array Cron jobs ready to be run.
     1116 * @return array[] Array of cron job arrays ready to be run.
    11171117 */
    11181118function wp_get_ready_cron_jobs() {
     
    11251125     * @since 5.1.0
    11261126     *
    1127      * @param null|array $pre Array of ready cron tasks to return instead. Default null
    1128      *                        to continue using results from _get_cron_array().
     1127     * @param null|array[] $pre Array of ready cron tasks to return instead. Default null
     1128     *                          to continue using results from _get_cron_array().
    11291129     */
    11301130    $pre = apply_filters( 'pre_get_ready_cron_jobs', null );
     
    11651165 * @access private
    11661166 *
    1167  * @return array|false Cron info array on success, false on failure.
     1167 * @return array[]|false Array of cron info arrays on success, false on failure.
    11681168 */
    11691169function _get_cron_array() {
     
    11911191 * @access private
    11921192 *
    1193  * @param array $cron     Cron info array from _get_cron_array().
    1194  * @param bool  $wp_error Optional. Whether to return a WP_Error on failure. Default false.
     1193 * @param array[] $cron     Array of cron info arrays from _get_cron_array().
     1194 * @param bool    $wp_error Optional. Whether to return a WP_Error on failure. Default false.
    11951195 * @return bool|WP_Error True if cron array updated. False or WP_Error on failure.
    11961196 */
  • trunk/src/wp-includes/rest-api/endpoints/class-wp-rest-pattern-directory-controller.php

    r51786 r52236  
    5252
    5353    /**
    54      * Checks whether a given request has permission to view the local pattern directory.
     54     * Checks whether a given request has permission to view the local block pattern directory.
    5555     *
    5656     * @since 5.8.0
     
    197197
    198198    /**
    199      * Prepare a raw pattern before it's output in an API response.
     199     * Prepare a raw block pattern before it gets output in a REST API response.
    200200     *
    201201     * @since 5.8.0
     
    224224
    225225        /**
    226          * Filters the REST API response for a pattern.
     226         * Filters the REST API response for a block pattern.
    227227         *
    228228         * @since 5.8.0
    229229         *
    230230         * @param WP_REST_Response $response    The response object.
    231          * @param object           $raw_pattern The unprepared pattern.
     231         * @param object           $raw_pattern The unprepared block pattern.
    232232         * @param WP_REST_Request  $request     The request object.
    233233         */
     
    236236
    237237    /**
    238      * Retrieves the pattern's schema, conforming to JSON Schema.
     238     * Retrieves the block pattern's schema, conforming to JSON Schema.
    239239     *
    240240     * @since 5.8.0
     
    308308
    309309    /**
    310      * Retrieves the search params for the patterns collection.
     310     * Retrieves the search parameters for the block pattern's collection.
    311311     *
    312312     * @since 5.8.0
     
    337337
    338338        /**
    339          * Filter collection parameters for the pattern directory controller.
     339         * Filter collection parameters for the block pattern directory controller.
    340340         *
    341341         * @since 5.8.0
Note: See TracChangeset for help on using the changeset viewer.