Make WordPress Core

Changeset 55693


Ignore:
Timestamp:
04/27/2023 10:27:51 PM (23 months ago)
Author:
johnbillion
Message:

Docs: Correct and improve various documented types for properties, functions, and hooks.

See #57840

Location:
trunk/src
Files:
8 edited

Legend:

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

    r55293 r55693  
    9090     *
    9191     * @since 3.3.0
    92      * @var string
     92     * @var string|null
    9393     */
    9494    public $parent_base;
     
    100100     *
    101101     * @since 3.3.0
    102      * @var string
     102     * @var string|null
    103103     */
    104104    public $parent_file;
  • trunk/src/wp-includes/block-template-utils.php

    r55687 r55693  
    6060 * @since 5.9.0
    6161 *
    62  * @return array The supported template part area values.
     62 * @return array[] The supported template part area values.
    6363 */
    6464function get_allowed_block_template_part_areas() {
     
    9898     * @since 5.9.0
    9999     *
    100      * @param array $default_area_definitions An array of supported area objects.
     100     * @param array[] $default_area_definitions An array of supported area objects.
    101101     */
    102102    return apply_filters( 'default_wp_template_part_areas', $default_area_definitions );
     
    110110 * @since 5.9.0
    111111 *
    112  * @return array The default template types.
     112 * @return array[] The default template types.
    113113 */
    114114function get_default_block_template_types() {
     
    185185     * @since 5.9.0
    186186     *
    187      * @param array $default_template_types An array of template types, formatted as [ slug => [ title, description ] ].
     187     * @param array[] $default_template_types An array of template types, formatted as [ slug => [ title, description ] ].
    188188     */
    189189    return apply_filters( 'default_template_types', $default_template_types );
     
    228228 *
    229229 * @param string $base_directory The theme's file path.
    230  * @return array A list of paths to all template part files.
     230 * @return string[] A list of paths to all template part files.
    231231 */
    232232function _get_block_templates_paths( $base_directory ) {
     
    927927 *     Optional. Arguments to retrieve templates.
    928928 *
    929  *     @type array $slug__in  List of slugs to include.
    930  *     @type int    $wp_id     Post ID of customized template.
    931  *     @type string $area      A 'wp_template_part_area' taxonomy value to filter by (for wp_template_part template type only).
    932  *     @type string $post_type Post type to get the templates for.
     929 *     @type string[] $slug__in  List of slugs to include.
     930 *     @type int      $wp_id     Post ID of customized template.
     931 *     @type string   $area      A 'wp_template_part_area' taxonomy value to filter by (for 'wp_template_part' template type only).
     932 *     @type string   $post_type Post type to get the templates for.
    933933 * }
    934934 * @param string $template_type 'wp_template' or 'wp_template_part'.
    935  * @return array Templates.
     935 * @return WP_Block_Template[] Array of block templates.
    936936 */
    937937function get_block_templates( $query = array(), $template_type = 'wp_template' ) {
     
    944944     *
    945945     * @param WP_Block_Template[]|null $block_templates Return an array of block templates to short-circuit the default query,
    946      *                                                  or null to allow WP to run it's normal queries.
     946     *                                                  or null to allow WP to run its normal queries.
    947947     * @param array  $query {
    948      *     Optional. Arguments to retrieve templates.
    949      *
    950      *     @type array  $slug__in List of slugs to include.
    951      *     @type int    $wp_id Post ID of customized template.
    952      *     @type string $post_type Post type to get the templates for.
     948     *     Arguments to retrieve templates. All arguments are optional.
     949     *
     950     *     @type string[] $slug__in  List of slugs to include.
     951     *     @type int      $wp_id     Post ID of customized template.
     952     *     @type string   $area      A 'wp_template_part_area' taxonomy value to filter by (for 'wp_template_part' template type only).
     953     *     @type string   $post_type Post type to get the templates for.
    953954     * }
    954      * @param string $template_type wp_template or wp_template_part.
     955     * @param string $template_type 'wp_template' or 'wp_template_part'.
    955956     */
    956957    $templates = apply_filters( 'pre_get_block_templates', null, $query, $template_type );
     
    10371038     *
    10381039     * @param WP_Block_Template[] $query_result Array of found block templates.
    1039      * @param array  $query {
    1040      *     Optional. Arguments to retrieve templates.
    1041      *
    1042      *     @type array  $slug__in List of slugs to include.
    1043      *     @type int    $wp_id Post ID of customized template.
     1040     * @param array               $query {
     1041     *     Arguments to retrieve templates. All arguments are optional.
     1042     *
     1043     *     @type string[] $slug__in  List of slugs to include.
     1044     *     @type int      $wp_id     Post ID of customized template.
     1045     *     @type string   $area      A 'wp_template_part_area' taxonomy value to filter by (for 'wp_template_part' template type only).
     1046     *     @type string   $post_type Post type to get the templates for.
    10441047     * }
    1045      * @param string $template_type wp_template or wp_template_part.
     1048     * @param string              $template_type wp_template or wp_template_part.
    10461049     */
    10471050    return apply_filters( 'get_block_templates', $query_result, $query, $template_type );
  • trunk/src/wp-includes/class-wp-block-patterns-registry.php

    r55174 r55693  
    5151     *     List of properties for the block pattern.
    5252     *
    53      *     @type string $title         Required. A human-readable title for the pattern.
    54      *     @type string $content       Required. Block HTML markup for the pattern.
    55      *     @type string $description   Optional. Visually hidden text used to describe the pattern
    56      *                                 in the inserter. A description is optional, but is strongly
    57      *                                 encouraged when the title does not fully describe what the
    58      *                                 pattern does. The description will help users discover the
    59      *                                 pattern while searching.
    60      *     @type int    $viewportWidth Optional. The intended width of the pattern to allow for a scaled
    61      *                                 preview within the pattern inserter.
    62      *     @type bool   $inserter      Optional. Determines whether the pattern is visible in inserter.
    63      *                                 To hide a pattern so that it can only be inserted programmatically,
    64      *                                 set this to false. Default true.
    65      *     @type array $categories    Optional. A list of registered pattern categories used to group
    66      *                                 block patterns. Block patterns can be shown on multiple categories.
    67      *                                 A category must be registered separately in order to be used here.
    68      *     @type array $keywords      Optional. A list of aliases or keywords that help users discover
    69      *                                 the pattern while searching.
    70      *     @type array $blockTypes    Optional. A list of block names including namespace that could use
    71      *                                 the block pattern in certain contexts (placeholder, transforms).
    72      *                                 The block pattern is available in the block editor inserter
    73      *                                 regardless of this list of block names.
    74      *                                 Certain blocks support further specificity besides the block name
    75      *                                 (e.g. for `core/template-part` you can specify areas
    76      *                                 like `core/template-part/header` or `core/template-part/footer`).
    77      *     @type array $postTypes     Optional. An array of post types that the pattern is restricted
    78      *                                 to be used with. The pattern will only be available when editing one
    79      *                                 of the post types passed on the array. For all the other post types
    80      *                                 not part of the array the pattern is not available at all.
    81      *     @type array $templateTypes Optional. An array of template types where the pattern fits.
     53     *     @type string   $title         Required. A human-readable title for the pattern.
     54     *     @type string   $content       Required. Block HTML markup for the pattern.
     55     *     @type string   $description   Optional. Visually hidden text used to describe the pattern
     56     *                                   in the inserter. A description is optional, but is strongly
     57     *                                   encouraged when the title does not fully describe what the
     58     *                                   pattern does. The description will help users discover the
     59     *                                   pattern while searching.
     60     *     @type int      $viewportWidth Optional. The intended width of the pattern to allow for a scaled
     61     *                                   preview within the pattern inserter.
     62     *     @type bool     $inserter      Optional. Determines whether the pattern is visible in inserter.
     63     *                                   To hide a pattern so that it can only be inserted programmatically,
     64     *                                   set this to false. Default true.
     65     *     @type string[] $categories    Optional. A list of registered pattern categories used to group
     66     *                                   block patterns. Block patterns can be shown on multiple categories.
     67     *                                   A category must be registered separately in order to be used here.
     68     *     @type string[] $keywords      Optional. A list of aliases or keywords that help users discover
     69     *                                   the pattern while searching.
     70     *     @type string[] $blockTypes    Optional. A list of block names including namespace that could use
     71     *                                   the block pattern in certain contexts (placeholder, transforms).
     72     *                                   The block pattern is available in the block editor inserter
     73     *                                   regardless of this list of block names.
     74     *                                   Certain blocks support further specificity besides the block name
     75     *                                   (e.g. for `core/template-part` you can specify areas
     76     *                                   like `core/template-part/header` or `core/template-part/footer`).
     77     *     @type string[] $postTypes     Optional. An array of post types that the pattern is restricted
     78     *                                   to be used with. The pattern will only be available when editing one
     79     *                                   of the post types passed on the array. For all the other post types
     80     *                                   not part of the array the pattern is not available at all.
     81     *     @type string[] $templateTypes Optional. An array of template types where the pattern fits.
    8282     * }
    8383     * @return bool True if the pattern was registered with success and false otherwise.
  • trunk/src/wp-includes/class-wp-block-template.php

    r54133 r55693  
    8585     *
    8686     * @since 5.9.0
    87      * @var string
     87     * @var string|null
    8888     */
    8989    public $origin;
     
    128128     *
    129129     * @since 5.9.0
    130      * @var int
     130     * @var int|null
    131131     */
    132132    public $author;
     
    136136     *
    137137     * @since 5.9.0
    138      * @var array
     138     * @var string[]|null
    139139     */
    140140    public $post_types;
     
    144144     *
    145145     * @since 5.9.0
    146      * @var string
     146     * @var string|null
    147147     */
    148148    public $area;
  • trunk/src/wp-includes/http.php

    r55650 r55693  
    594594     * @since 5.9.0
    595595     *
    596      * @param array  $allowed_ports Array of integers for valid ports.
     596     * @param int[]  $allowed_ports Array of integers for valid ports.
    597597     * @param string $host          Host name of the requested URL.
    598598     * @param string $url           Requested URL.
  • trunk/src/wp-includes/link-template.php

    r55526 r55693  
    47234723 * Returns an array of URL hosts which are considered to be internal hosts.
    47244724 *
    4725  * By default the list of internal hosts is comproside of the PHP_URL_HOST of
     4725 * By default the list of internal hosts is comprised of the host name of
    47264726 * the site's home_url() (as parsed by wp_parse_url()).
    47274727 *
     
    47464746         * @since 6.2.0
    47474747         *
    4748          * @param array $internal_hosts An array of internal URL hostnames.
     4748         * @param string[] $internal_hosts An array of internal URL hostnames.
    47494749         */
    47504750        $internal_hosts = apply_filters(
  • trunk/src/wp-includes/rest-api/class-wp-rest-server.php

    r55361 r55693  
    159159     * @since 4.4.0
    160160     *
    161      * @return WP_Error|null WP_Error indicates unsuccessful login, null indicates successful
    162      *                       or no authentication provided
     161     * @return WP_Error|null|true WP_Error indicates unsuccessful login, null indicates successful
     162     *                            or no authentication provided
    163163     */
    164164    public function check_authentication() {
  • trunk/src/wp-includes/taxonomy.php

    r55671 r55693  
    815815 * @param int|int[]       $term_ids   Term ID or array of term IDs of terms that will be used.
    816816 * @param string|string[] $taxonomies String of taxonomy name or Array of string values of taxonomy names.
    817  * @param array|string    $args       Change the order of the object IDs, either ASC or DESC.
     817 * @param array|string    $args       {
     818 *     Change the order of the object IDs.
     819 *
     820 *     @type string $order Order to retrieve terms. Accepts 'ASC' or 'DESC'. Default 'ASC'.
     821 * }
    818822 * @return string[]|WP_Error An array of object IDs as numeric strings on success,
    819823 *                           WP_Error if the taxonomy does not exist.
Note: See TracChangeset for help on using the changeset viewer.