WordPress.org
Get WordPress

Make WordPress Core

Changeset 51300


Ignore:
Timestamp:
07/01/2021 09:11:48 PM (4 years ago)
Author:
johnbillion
Message:

Docs: Descriptive improvements and corrections for various docblocks.

See #53399

Location:
trunk
Files:
19 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-admin/includes/file.php

    r50979 r51300  
    734734 * @see wp_handle_upload_error
    735735 *
    736  * @param string[]       $file      Reference to a single element of `$_FILES`.
    737  *                                  Call the function once for each uploaded file.
    738  * @param array|false    $overrides {
     736 * @param array       $file      {
     737 *     Reference to a single element from `$_FILES`. Call the function once for each uploaded file.
     738 *
     739 *     @type string $name     The original name of the file on the client machine.
     740 *     @type string $type     The mime type of the file, if the browser provided this information.
     741 *     @type string $tmp_name The temporary filename of the file in which the uploaded file was stored on the server.
     742 *     @type int    $size     The size, in bytes, of the uploaded file.
     743 *     @type int    $error    The error code associated with this file upload.
     744 * }
     745 * @param array|false $overrides {
    739746 *     An array of override parameters for this file, or boolean false if none are provided.
    740747 *
    … …  
    750757 *     @type string[] $mimes                    Array of allowed mime types keyed by their file extension regex.
    751758 * }
    752  * @param string         $time      Time formatted in 'yyyy/mm'.
    753  * @param string         $action    Expected value for `$_POST['action']`.
    754  * @return string[] On success, returns an associative array of file attributes.
    755  *                  On failure, returns `$overrides['upload_error_handler']( &$file, $message )`
    756  *                  or `array( 'error' => $message )`.
     759 * @param string      $time      Time formatted in 'yyyy/mm'.
     760 * @param string      $action    Expected value for `$_POST['action']`.
     761 * @return array {
     762 *     On success, returns an associative array of file attributes.
     763 *     On failure, returns `$overrides['upload_error_handler']( &$file, $message )`
     764 *     or `array( 'error' => $message )`.
     765 *
     766 *     @type string $file Filename of the newly-uploaded file.
     767 *     @type string $url  URL of the newly-uploaded file.
     768 *     @type string $type Mime type of the newly-uploaded file.
     769 * }
    757770 */
    758771function _wp_handle_upload( &$file, $overrides, $time, $action ) {
    … …  
    777790     * @since 4.0.0 Converted to a dynamic hook with `$action`.
    778791     *
    779      * @param string[] $file An array of data for the file. Reference to a single element of `$_FILES`.
     792     * @param array $file {
     793     *     Reference to a single element from `$_FILES`.
     794     *
     795     *     @type string $name     The original name of the file on the client machine.
     796     *     @type string $type     The mime type of the file, if the browser provided this information.
     797     *     @type string $tmp_name The temporary filename of the file in which the uploaded file was stored on the server.
     798     *     @type int    $size     The size, in bytes, of the uploaded file.
     799     *     @type int    $error    The error code associated with this file upload.
     800     * }
    780801     */
    781802    $file = apply_filters( "{$action}_prefilter", $file );
    … …  
    795816     * @param array|false $overrides An array of override parameters for this file. Boolean false if none are
    796817     *                               provided. @see _wp_handle_upload().
    797      * @param string[]    $file      An array of data for the file. Reference to a single element of `$_FILES`.
     818     * @param array       $file      {
     819     *     Reference to a single element from `$_FILES`.
     820     *
     821     *     @type string $name     The original name of the file on the client machine.
     822     *     @type string $type     The mime type of the file, if the browser provided this information.
     823     *     @type string $tmp_name The temporary filename of the file in which the uploaded file was stored on the server.
     824     *     @type int    $size     The size, in bytes, of the uploaded file.
     825     *     @type int    $error    The error code associated with this file upload.
     826     * }
    798827     */
    799828    $overrides = apply_filters( "{$action}_overrides", $overrides, $file );
    … …  
    936965     *
    937966     * @param mixed    $move_new_file If null (default) move the file after the upload.
    938      * @param string[] $file          An array of data for a single file.
     967     * @param array    $file          {
     968     *     Reference to a single element from `$_FILES`.
     969     *
     970     *     @type string $name     The original name of the file on the client machine.
     971     *     @type string $type     The mime type of the file, if the browser provided this information.
     972     *     @type string $tmp_name The temporary filename of the file in which the uploaded file was stored on the server.
     973     *     @type int    $size     The size, in bytes, of the uploaded file.
     974     *     @type int    $error    The error code associated with this file upload.
     975     * }
    939976     * @param string   $new_file      Filename of the newly-uploaded file.
    940977     * @param string   $type          Mime type of the newly-uploaded file.
    … …  
    10181055 * @param array       $file      Reference to a single element of `$_FILES`.
    10191056 *                               Call the function once for each uploaded file.
     1057 *                               See _wp_handle_upload() for accepted values.
    10201058 * @param array|false $overrides Optional. An associative array of names => values
    10211059 *                               to override default variables. Default false.
     1060 *                               See _wp_handle_upload() for accepted values.
    10221061 * @param string      $time      Optional. Time formatted in 'yyyy/mm'. Default null.
    1023  * @return array On success, returns an associative array of file attributes.
    1024  *               On failure, returns `$overrides['upload_error_handler']( &$file, $message )`
    1025  *               or `array( 'error' => $message )`.
     1062 * @return array See _wp_handle_upload() for return value.
    10261063 */
    10271064function wp_handle_upload( &$file, $overrides = false, $time = null ) {
    … …  
    10491086 * @param array       $file      Reference to a single element of `$_FILES`.
    10501087 *                               Call the function once for each uploaded file.
     1088 *                               See _wp_handle_upload() for accepted values.
    10511089 * @param array|false $overrides Optional. An associative array of names => values
    10521090 *                               to override default variables. Default false.
     1091 *                               See _wp_handle_upload() for accepted values.
    10531092 * @param string      $time      Optional. Time formatted in 'yyyy/mm'. Default null.
    1054  * @return array On success, returns an associative array of file attributes.
    1055  *               On failure, returns `$overrides['upload_error_handler']( &$file, $message )`
    1056  *               or `array( 'error' => $message )`.
     1093 * @return array See _wp_handle_upload() for return value.
    10571094 */
    10581095function wp_handle_sideload( &$file, $overrides = false, $time = null ) {

  • trunk/src/wp-includes/block-supports/elements.php

    r51299 r51300  
    1313 * @access private
    1414 *
    15  * @param string $block_content Rendered block content.
    16  * @param array  $block         Block object.
    17  * @return string Filtered block content.
     15 * @param  string $block_content Rendered block content.
     16 * @param  array  $block         Block object.
     17 * @return string                Filtered block content.
    1818 */
    1919function wp_render_elements_support( $block_content, $block ) {
    … …  
    2424
    2525    /*
    26      * For now we only care about link color.
    27      * This code in the future when we have a public API
    28      * should take advantage of WP_Theme_JSON::compute_style_properties
    29      * and work for any element and style.
    30      */
     26    * For now we only care about link color.
     27    * This code in the future when we have a public API
     28    * should take advantage of WP_Theme_JSON::compute_style_properties
     29    * and work for any element and style.
     30    */
    3131    if ( null === $link_color ) {
    3232        return $block_content;

  • trunk/src/wp-includes/block-supports/layout.php

    r51299 r51300  
    3636 * @access private
    3737 *
    38  * @param string $block_content Rendered block content.
    39  * @param array  $block         Block object.
    40  * @return string Filtered block content.
     38 * @param  string $block_content Rendered block content.
     39 * @param  array  $block         Block object.
     40 * @return string                Filtered block content.
    4141 */
    4242function wp_render_layout_support_flag( $block_content, $block ) {

  • trunk/src/wp-includes/block-template-utils.php

    r51221 r51300  
    104104 * @since 5.8.0
    105105 *
    106  * @param string $id Template unique identifier (example: theme_slug//template_slug).
    107  * @param string $template_type wp_template.
    108  *
     106 * @param string $id            Template unique identifier (example: theme_slug//template_slug).
     107 * @param string $template_type Optional. The template type (post type). Default 'wp_template'.
    109108 * @return WP_Block_Template|null Template.
    110109 */

  • trunk/src/wp-includes/class-http.php

    r51299 r51300  
    111111     *                                             assumed. Default 'GET'.
    112112     *     @type float        $timeout             How long the connection should stay open in seconds. Default 5.
    113      *     @type int          $redirection         Number of allowed redirects. Not supported by all transports.
     113     *     @type int          $redirection         Number of allowed redirects. Not supported by all transports
    114114     *                                             Default 5.
    115115     *     @type string       $httpversion         Version of the HTTP protocol to use. Accepts '1.0' and '1.1'.

  • trunk/src/wp-includes/class-wp-http-requests-hooks.php

    r49671 r51300  
    6464         * This action maps Requests internal hook to a native WordPress action.
    6565         *
    66          * @see https://github.com/rmccue/Requests/blob/master/docs/hooks.md
     66         * @see https://github.com/WordPress/Requests/blob/master/docs/hooks.md
    6767         *
    6868         * @since 4.7.0

  • trunk/src/wp-includes/class-wp-query.php

    r51299 r51300  
    1919
    2020    /**
    21      * Query vars set by the user.
     21     * Query vars set by the user
    2222     *
    2323     * @since 1.5.0
    … …  
    2727
    2828    /**
    29      * Query vars, after parsing.
     29     * Query vars, after parsing
    3030     *
    3131     * @since 1.5.0
    … …  
    3535
    3636    /**
    37      * Taxonomy query, as passed to get_tax_sql().
     37     * Taxonomy query, as passed to get_tax_sql()
    3838     *
    3939     * @since 3.1.0
    … …  
    4343
    4444    /**
    45      * Metadata query container.
     45     * Metadata query container
    4646     *
    4747     * @since 3.2.0
    … …  
    5151
    5252    /**
    53      * Date query container.
     53     * Date query container
    5454     *
    5555     * @since 3.7.0
    … …  
    9393
    9494    /**
    95      * The number of posts for the current query.
     95     * The amount of posts for the current query.
    9696     *
    9797     * @since 1.5.0
    … …  
    136136
    137137    /**
    138      * The number of comments for the posts.
     138     * The amount of comments for the posts.
    139139     *
    140140     * @since 2.2.0
    … …  
    160160
    161161    /**
    162      * The number of found posts for the current query.
     162     * The amount of found posts for the current query.
    163163     *
    164164     * If limit clause was not used, equals $post_count.
    … …  
    170170
    171171    /**
    172      * The number of pages.
     172     * The amount of pages.
    173173     *
    174174     * @since 2.1.0
    … …  
    178178
    179179    /**
    180      * The number of comment pages.
     180     * The amount of comment pages.
    181181     *
    182182     * @since 2.7.0

  • trunk/src/wp-includes/class-wp-term-query.php

    r51299 r51300  
    9393     *     Optional. Array or query string of term query parameters. Default empty.
    9494     *
    95      *     @type string|array $taxonomy               Taxonomy name, or array of taxonomies, to which results should
     95     *     @type string|array $taxonomy               Taxonomy name, or array of taxonomy names, to which results should
    9696     *                                                be limited.
    97      *     @type int|int[]    $object_ids             Object ID, or array of object IDs. Results will be
     97     *     @type int|int[]    $object_ids             Optional. Object ID, or array of object IDs. Results will be
    9898     *                                                limited to terms associated with these objects.
    9999     *     @type string       $orderby                Field(s) to order terms by. Accepts:
    100      *                                                * Term fields ('name', 'slug', 'term_group', 'term_id', 'id',
     100     *                                                * term fields ('name', 'slug', 'term_group', 'term_id', 'id',
    101101     *                                                  'description', 'parent', 'term_order'). Unless `$object_ids`
    102102     *                                                  is not empty, 'term_order' is treated the same as 'term_id'.
    103103     *                                                * 'count' to use the number of objects associated with the term.
    104      *                                                * 'include' to match the 'order' of the `$include` param.
    105      *                                                * 'slug__in' to match the 'order' of the `$slug` param.
    106      *                                                * 'meta_value'
    107      *                                                * 'meta_value_num'.
    108      *                                                * The value of `$meta_key`.
    109      *                                                * The array keys of `$meta_query`.
     104     *                                                * 'include' to match the 'order' of the $include param.
     105     *                                                * 'slug__in' to match the 'order' of the $slug param.
     106     *                                                * 'meta_value', 'meta_value_num'.
     107     *                                                  the value of `$meta_key`.
     108     *                                                  the array keys of `$meta_query`.
    110109     *                                                * 'none' to omit the ORDER BY clause.
    111      *                                                Default 'name'.
     110     *                                                Defaults to 'name'.
    112111     *     @type string       $order                  Whether to order terms in ascending or descending order.
    113112     *                                                Accepts 'ASC' (ascending) or 'DESC' (descending).
    … …  
    118117     *                                                Default empty array.
    119118     *     @type int[]|string $exclude                Array or comma/space-separated string of term IDs to exclude.
    120      *                                                If `$include` is non-empty, `$exclude` is ignored.
     119     *                                                If $include is non-empty, $exclude is ignored.
    121120     *                                                Default empty array.
    122121     *     @type int[]|string $exclude_tree           Array or comma/space-separated string of term IDs to exclude
    123      *                                                along with all of their descendant terms. If `$include` is
    124      *                                                non-empty, `$exclude_tree` is ignored. Default empty array.
     122     *                                                along with all of their descendant terms. If $include is
     123     *                                                non-empty, $exclude_tree is ignored. Default empty array.
    125124     *     @type int|string   $number                 Maximum number of terms to return. Accepts ''|0 (all) or any
    126125     *                                                positive number. Default ''|0 (all). Note that $number may
    127      *                                                not return accurate results when coupled with `$object_ids`.
     126     *                                                not return accurate results when coupled with $object_ids.
    128127     *                                                See #41796 for details.
    129128     *     @type int          $offset                 The number by which to offset the terms query. Default empty.
    … …  
    147146     *     @type bool         $count                  Whether to return a term count. If true, will take precedence
    148147     *                                                over `$fields`. Default false.
    149      *     @type string|array $name                   Name or array of names to return term(s) for.
     148     *     @type string|array $name                   Optional. Name or array of names to return term(s) for.
    150149     *                                                Default empty.
    151      *     @type string|array $slug                   Slug or array of slugs to return term(s) for.
     150     *     @type string|array $slug                   Optional. Slug or array of slugs to return term(s) for.
    152151     *                                                Default empty.
    153      *     @type int|int[]    $term_taxonomy_id       Term taxonomy ID, or array of term taxonomy IDs,
     152     *     @type int|int[]    $term_taxonomy_id       Optional. Term taxonomy ID, or array of term taxonomy IDs,
    154153     *                                                to match when querying terms.
    155154     *     @type bool         $hierarchical           Whether to include terms that have non-empty descendants
    156      *                                                (even if `$hide_empty` is set to true). Default true.
     155     *                                                (even if $hide_empty is set to true). Default true.
    157156     *     @type string       $search                 Search criteria to match terms. Will be SQL-formatted with
    158157     *                                                wildcards before and after. Default empty.
    … …  
    165164     *                                                Default false.
    166165     *     @type string       $get                    Whether to return terms regardless of ancestry or whether the
    167      *                                                terms are empty. Accepts 'all' or '' (disabled).
    168      *                                                Default ''.
     166     *                                                terms are empty. Accepts 'all' or empty (disabled).
     167     *                                                Default empty.
    169168     *     @type int          $child_of               Term ID to retrieve child terms of. If multiple taxonomies
    170169     *                                                are passed, `$child_of` is ignored. Default 0.
    … …  
    175174     *                                                Default false.
    176175     *     @type string       $cache_domain           Unique cache key to be produced when this query is stored in
    177      *                                                an object cache. Default 'core'.
     176     *                                                an object cache. Default is 'core'.
    178177     *     @type bool         $update_term_meta_cache Whether to prime meta caches for matched terms. Default true.
    179      *     @type array        $meta_query             Meta query clauses to limit retrieved terms by.
     178     *     @type array        $meta_query             Optional. Meta query clauses to limit retrieved terms by.
    180179     *                                                See `WP_Meta_Query`. Default empty.
    181180     *     @type string       $meta_key               Limit terms to those matching a specific metadata key.

  • trunk/src/wp-includes/comment-template.php

    r51084 r51300  
    263263 * @param int|WP_Comment $comment_ID Optional. WP_Comment or the ID of the comment for which to get the author's IP address.
    264264 *                                   Default current comment.
    265  * @return string Comment author's IP address.
     265 * @return string Comment author's IP address, or an empty string if it's not available.
    266266 */
    267267function get_comment_author_IP( $comment_ID = 0 ) { // phpcs:ignore WordPress.NamingConventions.ValidFunctionName.FunctionNameInvalid
    … …  
    274274     * @since 4.1.0 The `$comment_ID` and `$comment` parameters were added.
    275275     *
    276      * @param string     $comment_author_IP The comment author's IP address.
     276     * @param string     $comment_author_IP The comment author's IP address, or an empty string if it's not available.
    277277     * @param int        $comment_ID        The comment ID.
    278278     * @param WP_Comment $comment           The comment object.

  • trunk/src/wp-includes/customize/class-wp-customize-date-time-control.php

    r49108 r51300  
    215215     * @since 4.9.0
    216216     *
    217      * @return array abbr and description.
     217     * @return array {
     218     *     Timezone info. All properties are optional.
     219     *
     220     *     @type string $abbr        Timezone abbreviation, eg. PST or CEST.
     221     *     @type string $description Human-readable timezone description as HTML.
     222     * }
    218223     */
    219224    public function get_timezone_info() {

  • trunk/src/wp-includes/functions.php

    r51223 r51300  
    218218 *
    219219 * @since 5.3.0
     220 *
     221 * @global WP_Locale $wp_locale WordPress date and time locale object.
    220222 *
    221223 * @param string       $format    PHP date format.

  • trunk/src/wp-includes/kses.php

    r51007 r51300  
    855855    if ( is_array( $context ) ) {
    856856        /**
    857          * Filters the HTML that is allowed for a given context.
     857         * Filters the HTML tags that are allowed for a given context.
    858858         *
    859859         * @since 3.5.0
    … …  
    10411041 * @global string[]       $pass_allowed_protocols Array of allowed URL protocols.
    10421042 *
    1043  * @param array $matches preg_replace regexp matches
     1043 * @param array $match preg_replace regexp matches
    10441044 * @return string
    10451045 */

  • trunk/src/wp-includes/load.php

    r51299 r51300  
    676676     *
    677677     * @param bool $enable_object_cache Whether to enable loading object-cache.php (if present).
    678      *                                  Default true.
     678     *                                    Default true.
    679679     */
    680680    if ( $first_init && apply_filters( 'enable_loading_object_cache_dropin', true ) ) {

  • trunk/src/wp-includes/nav-menu.php

    r51299 r51300  
    160160 * @since 3.0.0
    161161 *
    162  * @return int[] Associative array of registered navigation menu IDs keyed by their
     162 * @return int[] Associative array of egistered navigation menu IDs keyed by their
    163163 *               location name. If none are registered, an empty array.
    164164 */

  • trunk/src/wp-includes/pluggable.php

    r51299 r51300  
    27862786         * @param string $default     URL for the default image or a default type. Accepts '404', 'retro', 'monsterid',
    27872787         *                            'wavatar', 'indenticon', 'mystery', 'mm', 'mysteryman', 'blank', or 'gravatar_default'.
    2788          * @param string $alt         Alternative text to use in the avatar image tag.
     2788         *                            Default is the value of the 'avatar_default' option, with a fallback of 'mystery'.
     2789         * @param string $alt         Alternative text to use in the avatar image tag. Default empty.
    27892790         * @param array  $args        Arguments passed to get_avatar_data(), after processing.
    27902791         */

  • trunk/src/wp-includes/post.php

    r51299 r51300  
    13921392 *                                               the admin interface or by front-end users. While the default
    13931393 *                                               settings of $exclude_from_search, $publicly_queryable, $show_ui,
    1394  *                                               and $show_in_nav_menus are inherited from $public, each does not
     1394 *                                               and $show_in_nav_menus are inherited from public, each does not
    13951395 *                                               rely on this relationship and controls a very specific intention.
    13961396 *                                               Default false.
    … …  
    14181418 *     @type bool         $show_in_rest          Whether to include the post type in the REST API. Set this to true
    14191419 *                                               for the post type to be available in the block editor.
    1420  *     @type string       $rest_base             To change the base URL of REST API route. Default is $post_type.
    1421  *     @type string       $rest_controller_class REST API controller class name. Default is 'WP_REST_Posts_Controller'.
     1420 *     @type string       $rest_base             To change the base url of REST API route. Default is $post_type.
     1421 *     @type string       $rest_controller_class REST API Controller class name. Default is 'WP_REST_Posts_Controller'.
    14221422 *     @type int          $menu_position         The position in the menu order the post type should appear. To work,
    14231423 *                                               $show_in_menu must be true. Default null (at the bottom).
    1424  *     @type string       $menu_icon             The URL to the icon to be used for this menu. Pass a base64-encoded
     1424 *     @type string       $menu_icon             The url to the icon to be used for this menu. Pass a base64-encoded
    14251425 *                                               SVG using a data URI, which will be colored to match the color scheme
    14261426 *                                               -- this should begin with 'data:image/svg+xml;base64,'. Pass the name

  • trunk/src/wp-includes/user.php

    r51298 r51300  
    17501750 *     @type bool   $use_ssl              Whether the user should always access the admin over
    17511751 *                                        https. Default false.
    1752  *     @type string $user_registered      Date the user registered. Format is 'Y-m-d H:i:s'.
     1752 *     @type string $user_registered      Date the user registered in UTC. Format is 'Y-m-d H:i:s'.
    17531753 *     @type string $user_activation_key  Password reset key. Default empty.
    17541754 *     @type bool   $spam                 Multisite only. Whether the user is marked as spam.

  • trunk/src/wp-includes/widgets.php

    r51298 r51300  
    18331833function wp_use_widgets_block_editor() {
    18341834    /**
    1835      * Filters whether or not to use the block editor to manage widgets.
     1835     * Filters whether to use the block editor to manage widgets.
    18361836     *
    18371837     * @since 5.8.0

  • trunk/tests/phpunit/tests/http/functions.php

    r50344 r51300  
    222222        $requests_response->cookies['test'] = Requests_Cookie::parse( 'test=foo; domain=.wordpress.org' );
    223223
    224         $requests_response->cookies['test']->flags['host-only'] = false; // https://github.com/rmccue/Requests/issues/306
     224        $requests_response->cookies['test']->flags['host-only'] = false; // https://github.com/WordPress/Requests/issues/306
    225225
    226226        $http_response = new WP_HTTP_Requests_Response( $requests_response );
Note: See TracChangeset for help on using the changeset viewer.