WordPress.org
Get WordPress

Make WordPress Core

Changeset 52204


Ignore:
Timestamp:
11/18/2021 01:48:43 PM (5 years ago)
Author:
johnbillion
Message:

Docs: Various corrections and improvements relating to types used in inline documentation.

See #53399

Location:
trunk
Files:
30 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/wp-admin/includes/class-theme-installer-skin.php

    r50931 r52204  
    283283                 * @since 5.5.0
    284284                 *
    285                  * @param string $table              The output table with Name, Version, Author, RequiresWP, and RequiresPHP info.
    286                  * @param array  $current_theme_data Array with current theme data.
    287                  * @param array  $new_theme_data     Array with uploaded theme data.
     285                 * @param string   $table              The output table with Name, Version, Author, RequiresWP, and RequiresPHP info.
     286                 * @param WP_Theme $current_theme_data Current theme data.
     287                 * @param array    $new_theme_data     Array with uploaded theme data.
    288288                 */
    289289                echo apply_filters( 'install_theme_overwrite_comparison', $table, $current_theme_data, $new_theme_data );

  • trunk/src/wp-admin/includes/class-walker-nav-menu-edit.php

    r51779 r52204  
    243243                                 * @since 5.4.0
    244244                                 *
    245                                  * @param int      $item_id           Menu item ID.
    246                                  * @param WP_Post  $menu_item         Menu item data object.
    247                                  * @param int      $depth             Depth of menu item. Used for padding.
    248                                  * @param stdClass $args              An object of menu item arguments.
    249                                  * @param int      $current_object_id Nav menu ID.
     245                                 * @param string        $item_id           Menu item ID as a numeric string.
     246                                 * @param WP_Post       $menu_item         Menu item data object.
     247                                 * @param int           $depth             Depth of menu item. Used for padding.
     248                                 * @param stdClass|null $args              An object of menu item arguments.
     249                                 * @param int           $current_object_id Nav menu ID.
    250250                                 */
    251251                                do_action( 'wp_nav_menu_item_custom_fields', $item_id, $menu_item, $depth, $args, $current_object_id );

  • trunk/src/wp-admin/includes/class-wp-theme-install-list-table.php

    r50505 r52204  
    252252         * @global array $themes_allowedtags
    253253         *
    254          * @param object $theme {
     254         * @param stdClass $theme {
    255255         *     An object that contains theme data returned by the WordPress.org API.
    256256         *
    … …  
    353353                 * @param string[] $actions An array of theme action links. Defaults are
    354354                 *                          links to Install Now, Preview, and Details.
    355                  * @param WP_Theme $theme   Theme object.
     355                 * @param stdClass $theme   An object that contains theme data returned by the
     356                 *                          WordPress.org API.
    356357                 */
    357358                $actions = apply_filters( 'theme_install_actions', $actions, $theme );
    … …  
    413414         * Used to make the theme installer work for no-js.
    414415         *
    415          * @param object $theme - A WordPress.org Theme API object.
     416         * @param stdClass $theme A WordPress.org Theme API object.
    416417         */
    417418        public function theme_installer_single( $theme ) {
    … …  
    433434         * @global array $themes_allowedtags
    434435         *
    435          * @param object $theme - A WordPress.org Theme API object.
     436         * @param stdClass $theme A WordPress.org Theme API object.
    436437         */
    437438        public function install_theme_info( $theme ) {
    … …  
    547548         * @since 3.4.0
    548549         *
    549          * @param object $theme - A WordPress.org Theme API object.
     550         * @param stdClass $theme A WordPress.org Theme API object.
    550551         * @return string Theme status.
    551552         */

  • trunk/src/wp-admin/includes/class-wp-upgrader.php

    r52192 r52204  
    406406         *
    407407         * @param string $remote_destination The location on the remote filesystem to be cleared.
    408          * @return bool|WP_Error True upon success, WP_Error on failure.
     408         * @return true|WP_Error True upon success, WP_Error on failure.
    409409         */
    410410        public function clear_destination( $remote_destination ) {

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

    r52014 r52204  
    17281728         * @since 3.2.0
    17291729         *
    1730          * @param string $notice   The notice content.
    1731          * @param array  $response An array containing web browser information. See `wp_check_browser_version()`.
     1730         * @param string      $notice   The notice content.
     1731         * @param array|false $response An array containing web browser information, or
     1732         *                              false on failure. See `wp_check_browser_version()`.
    17321733         */
    17331734        echo apply_filters( 'browse-happy-notice', $notice, $response ); // phpcs:ignore WordPress.NamingConventions.ValidHookName.UseUnderscores

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

    r52171 r52204  
    36423642         * @param string $file           Path to video file.
    36433643         * @param string $file_format    File format of video, as analyzed by getID3.
    3644          * @param string $data           Raw metadata from getID3.
     3644         * @param array $data           Raw metadata from getID3.
    36453645         */
    36463646        return apply_filters( 'wp_read_video_metadata', $metadata, $file, $file_format, $data );

  • trunk/src/wp-admin/includes/meta-boxes.php

    r51943 r52204  
    985985                 * @since 4.4.0
    986986                 *
    987                  * @param string  $template The template used for the current post.
    988                  * @param WP_Post $post     The current post.
     987                 * @param string|false $template The template used for the current post.
     988                 * @param WP_Post      $post     The current post.
    989989                 */
    990990                do_action( 'page_attributes_meta_box_template', $template, $post );

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

    r51873 r52204  
    9797         * @see wp_terms_checklist()
    9898         *
    99          * @param array $args    An array of arguments.
    100          * @param int   $post_id The post ID.
     99         * @param array|string $args    An array or string of arguments.
     100         * @param int          $post_id The post ID.
    101101         */
    102102        $params = apply_filters( 'wp_terms_checklist_args', $args, $post_id );

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

    r51601 r52204  
    623623         * @since 2.8.0
    624624         *
    625          * @param array|object|WP_Error $res    WordPress.org Themes API response.
    626          * @param string                $action Requested action. Likely values are 'theme_information',
    627          *                                      'feature_list', or 'query_themes'.
    628          * @param object                $args   Arguments used to query for installer pages from the WordPress.org Themes API.
     625         * @param array|stdClass|WP_Error $res    WordPress.org Themes API response.
     626         * @param string                  $action Requested action. Likely values are 'theme_information',
     627         *                                        'feature_list', or 'query_themes'.
     628         * @param stdClass                $args   Arguments used to query for installer pages from the WordPress.org Themes API.
    629629         */
    630630        return apply_filters( 'themes_api_result', $res, $action, $args );

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

    r51463 r52204  
    2626 *
    2727 * @param int $user_id Optional. User ID.
    28  * @return int|WP_Error User ID of the updated user.
     28 * @return int|WP_Error User ID of the updated user or WP_Error on failure.
    2929 */
    3030function edit_user( $user_id = 0 ) {
    … …  
    235235                 * @since 4.4.0
    236236                 *
    237                  * @param int    $user_id ID of the newly created user.
    238                  * @param string $notify  Type of notification that should happen. See wp_send_new_user_notifications()
    239                  *                        for more information on possible values.
     237                 * @param int|WP_Error $user_id ID of the newly created user or WP_Error on failure.
     238                 * @param string       $notify  Type of notification that should happen. See
     239                 *                              wp_send_new_user_notifications() for more information.
    240240                 */
    241241                do_action( 'edit_user_created_user', $user_id, $notify );

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

    r52180 r52204  
    662662         * @since 2.1.0
    663663         *
    664          * @param string $output HTML output.
    665          * @param array  $args   An array of taxonomy-listing arguments. See wp_list_categories()
    666          *                       for information on accepted arguments.
     664         * @param string       $output HTML output.
     665         * @param array|string $args   An array or query string of taxonomy-listing arguments. See
     666         *                             wp_list_categories() for information on accepted arguments.
    667667         */
    668668        $html = apply_filters( 'wp_list_categories', $output, $args );

  • trunk/src/wp-includes/class-wp-customize-manager.php

    r51919 r52204  
    59245924                 * @see WP_Customize_Manager::__construct()
    59255925                 *
    5926                  * @param array                $themes  Nested array of theme data.
     5926                 * @param array|stdClass       $themes  Nested array or object of theme data.
    59275927                 * @param array                $args    List of arguments, such as page, search term, and tags to query for.
    59285928                 * @param WP_Customize_Manager $manager Instance of Customize manager.

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

    r52093 r52204  
    12141214         * @since 5.8.0 Include block templates.
    12151215         *
    1216          * @return string[] Array of page templates, keyed by filename and post type,
    1217          *                  with the value of the translated header name.
     1216         * @return array[] Array of page template arrays, keyed by post type and filename,
     1217         *                 with the value of the translated header name.
    12181218         */
    12191219        public function get_post_templates() {

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

    r52187 r52204  
    81358135 * @since 5.6.0 The `$directory_cache` parameter was added.
    81368136 *
    8137  * @param string       $directory          Full path of a directory.
    8138  * @param string|array $exclude            Optional. Full path of a subdirectory to exclude from the total,
    8139  *                                         or array of paths. Expected without trailing slash(es).
    8140  * @param int          $max_execution_time Optional. Maximum time to run before giving up. In seconds.
    8141  *                                         The timeout is global and is measured from the moment
    8142  *                                         WordPress started to load.
    8143  * @param array        $directory_cache    Optional. Array of cached directory paths.
     8137 * @param string          $directory          Full path of a directory.
     8138 * @param string|string[] $exclude            Optional. Full path of a subdirectory to exclude from the total,
     8139 *                                            or array of paths. Expected without trailing slash(es).
     8140 * @param int             $max_execution_time Optional. Maximum time to run before giving up. In seconds.
     8141 *                                            The timeout is global and is measured from the moment
     8142 *                                            WordPress started to load.
     8143 * @param array           $directory_cache    Optional. Array of cached directory paths.
    81448144 *
    81458145 * @return int|false|null Size in bytes if a valid directory. False if not. Null if timeout.
    … …  
    81928192         * @since 5.6.0
    81938193         *
    8194          * @param int|false $space_used The amount of used space, in bytes. Default false.
     8194         * @param int|false            $space_used         The amount of used space, in bytes. Default false.
     8195         * @param string               $directory          Full path of a directory.
     8196         * @param string|string[]|null $exclude            Full path of a subdirectory to exclude from the total,
     8197         *                                                 or array of paths.
     8198         * @param int                  $max_execution_time Maximum time to run before giving up. In seconds.
     8199         * @param array                $directory_cache    Array of cached directory paths.
    81958200         */
    81968201        $size = apply_filters( 'pre_recurse_dirsize', false, $directory, $exclude, $max_execution_time, $directory_cache );

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

    r52074 r52204  
    12721272         * @param int    $blog_id       Blog ID.
    12731273         * @param int    $user_id       User ID.
    1274          * @param int    $password      User password.
     1274         * @param string $password      User password.
    12751275         * @param string $signup_title  Site title.
    12761276         * @param array  $meta          Signup meta data. By default, contains the requested privacy setting and lang_id.

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

    r50791 r52204  
    10061006         * @since 3.6.0
    10071007         *
    1008          * @param string $output HTML output of paginated posts' page links.
    1009          * @param array  $args   An array of arguments. See wp_link_pages()
    1010          *                       for information on accepted arguments.
     1008         * @param string       $output HTML output of paginated posts' page links.
     1009         * @param array|string $args   An array or query string of arguments. See wp_link_pages()
     1010         *                             for information on accepted arguments.
    10111011         */
    10121012        $html = apply_filters( 'wp_link_pages', $output, $args );
    … …  
    16471647         *
    16481648         * @param string       $link_html The page link HTML output.
    1649          * @param int          $id        Post ID.
     1649         * @param int|WP_Post  $id        Post ID or object. Can be 0 for the current global post.
    16501650         * @param string|int[] $size      Requested image size. Can be any registered image size name, or
    16511651         *                                an array of width and height values in pixels (in that order).

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

    r52065 r52204  
    225225         * @param string       $html              The post thumbnail HTML.
    226226         * @param int          $post_id           The post ID.
    227          * @param int          $post_thumbnail_id The post thumbnail ID.
     227         * @param int          $post_thumbnail_id The post thumbnail ID, or 0 if there isn't one.
    228228         * @param string|int[] $size              Requested image size. Can be any registered image size name, or
    229229         *                                        an array of width and height values in pixels (in that order).
    230          * @param string       $attr              Query string of attributes.
     230         * @param string|array $attr              Query string or array of attributes.
    231231         */
    232232        return apply_filters( 'post_thumbnail_html', $html, $post->ID, $post_thumbnail_id, $size, $attr );

  • trunk/src/wp-includes/rest-api/class-wp-rest-server.php

    r52080 r52204  
    13981398
    13991399                        /**
    1400                          * Filters the REST API endpoint data.
     1400                         * Filters the publicly-visible data for a single REST API route.
    14011401                         *
    14021402                         * @since 4.4.0
    14031403                         *
    1404                          * @param WP_REST_Request $request Request data. The namespace is passed as the 'namespace' parameter.
     1404                         * @param array $data Publicly-visible data for the route.
    14051405                         */
    14061406                        $available[ $route ] = apply_filters( 'rest_endpoints_description', $data );

  • trunk/src/wp-includes/rest-api/endpoints/class-wp-rest-block-navigation-areas-controller.php

    r52161 r52204  
    212212         * @param stdClass        $area    Post status data.
    213213         * @param WP_REST_Request $request Full details about the request.
    214          * @return WP_REST_Response Post status data.
     214         * @return WP_REST_Response|WP_Error Response object on success, or WP_Error object on failure.
    215215         */
    216216        public function prepare_item_for_response( $area, $request ) {
    … …  
    247247                 * returned.
    248248                 *
    249                  * @param WP_REST_Response $response The response object.
    250                  * @param object           $area     The original status object.
    251                  * @param WP_REST_Request  $request  Request used to generate the response.
     249                 * @param WP_REST_Response\WP_Error $response The response object, or WP_Error object on failure.
     250                 * @param object                    $area     The original status object.
     251                 * @param WP_REST_Request           $request  Request used to generate the response.
    252252                 */
    253253                return apply_filters( 'rest_prepare_navigation_area', $response, $area, $request );

  • trunk/src/wp-includes/rest-api/endpoints/class-wp-rest-widgets-controller.php

    r52068 r52204  
    461461                 * @since 5.8.0
    462462                 *
    463                  * @param string           $widget_id  ID of the widget marked for deletion.
    464                  * @param string           $sidebar_id ID of the sidebar the widget was deleted from.
    465                  * @param WP_REST_Response $response   The response data.
    466                  * @param WP_REST_Request  $request    The request sent to the API.
     463                 * @param string                    $widget_id  ID of the widget marked for deletion.
     464                 * @param string                    $sidebar_id ID of the sidebar the widget was deleted from.
     465                 * @param WP_REST_Response|WP_Error $response   The response data, or WP_Error object on failure.
     466                 * @param WP_REST_Request           $request    The request sent to the API.
    467467                 */
    468468                do_action( 'rest_delete_widget', $widget_id, $sidebar_id, $response, $request );
    … …  
    734734                 * @since 5.8.0
    735735                 *
    736                  * @param WP_REST_Response $response The response object.
    737                  * @param array            $widget   The registered widget data.
    738                  * @param WP_REST_Request  $request  Request used to generate the response.
     736                 * @param WP_REST_Response|WP_Error $response The response object, or WP_Error object on failure.
     737                 * @param array                     $widget   The registered widget data.
     738                 * @param WP_REST_Request           $request  Request used to generate the response.
    739739                 */
    740740                return apply_filters( 'rest_prepare_widget', $response, $widget, $request );

  • trunk/src/wp-includes/sitemaps/class-wp-sitemaps-provider.php

    r51652 r52204  
    4343         * @param int    $page_num       Page of results.
    4444         * @param string $object_subtype Optional. Object subtype name. Default empty.
    45          * @return array Array of URLs for a sitemap.
     45         * @return array[] Array of URL information for a sitemap.
    4646         */
    4747        abstract public function get_url_list( $page_num, $object_subtype = '' );

  • trunk/src/wp-includes/sitemaps/providers/class-wp-sitemaps-posts.php

    r51788 r52204  
    6060         * @param string $object_subtype Optional. Post type name. Default empty.
    6161         *
    62          * @return array Array of URLs for a sitemap.
     62         * @return array[] Array of URL information for a sitemap.
    6363         */
    6464        public function get_url_list( $page_num, $object_subtype = '' ) {
    … …  
    8181                 * @since 5.5.0
    8282                 *
    83                  * @param array  $url_list  The URL list. Default null.
    84                  * @param string $post_type Post type name.
    85                  * @param int    $page_num  Page of results.
     83                 * @param array[]|null $url_list  The URL list. Default null.
     84                 * @param string       $post_type Post type name.
     85                 * @param int          $page_num  Page of results.
    8686                 */
    8787                $url_list = apply_filters(

  • trunk/src/wp-includes/sitemaps/providers/class-wp-sitemaps-taxonomies.php

    r51788 r52204  
    5757         * @param int    $page_num       Page of results.
    5858         * @param string $object_subtype Optional. Taxonomy name. Default empty.
    59          * @return array Array of URLs for a sitemap.
     59         * @return array[] Array of URL information for a sitemap.
    6060         */
    6161        public function get_url_list( $page_num, $object_subtype = '' ) {
    … …  
    7777                 * @since 5.5.0
    7878                 *
    79                  * @param array  $url_list The URL list. Default null.
    80                  * @param string $taxonomy Taxonomy name.
    81                  * @param int    $page_num Page of results.
     79                 * @param array[]|null $url_list The URL list. Default null.
     80                 * @param string       $taxonomy Taxonomy name.
     81                 * @param int          $page_num Page of results.
    8282                 */
    8383                $url_list = apply_filters(
    … …  
    150150
    151151                /**
    152                  * Filters the max number of pages before it is generated.
     152                 * Filters the max number of pages for a taxonomy sitemap before it is generated.
    153153                 *
    154154                 * Passing a non-null value will short-circuit the generation,
    … …  
    157157                 * @since 5.5.0
    158158                 *
    159                  * @param int    $max_num_pages The maximum number of pages. Default null.
    160                  * @param string $taxonomy      Taxonomy name.
     159                 * @param int|null $max_num_pages The maximum number of pages. Default null.
     160                 * @param string   $taxonomy      Taxonomy name.
    161161                 */
    162162                $max_num_pages = apply_filters( 'wp_sitemaps_taxonomies_pre_max_num_pages', null, $taxonomy );

  • trunk/src/wp-includes/sitemaps/providers/class-wp-sitemaps-users.php

    r48100 r52204  
    3535         *                               required for compatibility with the parent
    3636         *                               provider class. Default empty.
    37          * @return array Array of URLs for a sitemap.
     37         * @return array[] Array of URL information for a sitemap.
    3838         */
    3939        public function get_url_list( $page_num, $object_subtype = '' ) {
    … …  
    4646                 * @since 5.5.0
    4747                 *
    48                  * @param array  $url_list The URL list. Default null.
    49                  * @param int    $page_num Page of results.
     48                 * @param array[]|null $url_list The URL list. Default null.
     49                 * @param int        $page_num Page of results.
    5050                 */
    5151                $url_list = apply_filters(
    … …  
    100100        public function get_max_num_pages( $object_subtype = '' ) {
    101101                /**
    102                  * Filters the max number of pages before it is generated.
     102                 * Filters the max number of pages for a user sitemap before it is generated.
    103103                 *
    104104                 * Passing a non-null value will effectively short-circuit the generation,
    … …  
    107107                 * @since 5.5.0
    108108                 *
    109                  * @param int $max_num_pages The maximum number of pages. Default null.
     109                 * @param int|null $max_num_pages The maximum number of pages. Default null.
    110110                 */
    111111                $max_num_pages = apply_filters( 'wp_sitemaps_users_pre_max_num_pages', null );

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

    r52163 r52204  
    28932893 * @param int              $object_id The ID of the object from which the terms will be removed.
    28942894 * @param string|int|array $terms     The slug(s) or ID(s) of the term(s) to remove.
    2895  * @param array|string     $taxonomy  Taxonomy name.
     2895 * @param string           $taxonomy  Taxonomy name.
    28962896 * @return bool|WP_Error True on success, false or WP_Error on failure.
    28972897 */

  • trunk/src/wp-includes/theme-compat/embed-content.php

    r46586 r52204  
    2828                 * @since 4.9.0
    2929                 *
    30                  * @param int $thumbnail_id Attachment ID.
     30                 * @param int|false $thumbnail_id Attachment ID, or false if there is none.
    3131                 */
    3232                $thumbnail_id = apply_filters( 'embed_thumbnail_id', $thumbnail_id );

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

    r52016 r52204  
    490490         * @since 3.0.0
    491491         *
    492          * @param int $id The widget ID.
     492         * @param int|string $id The widget ID.
    493493         */
    494494        do_action( 'wp_unregister_sidebar_widget', $id );

  • trunk/tests/phpunit/includes/class-wp-sitemaps-empty-test-provider.php

    r48072 r52204  
    2121         * @param int    $page_num       Page of results.
    2222         * @param string $object_subtype Optional. Object subtype name. Default empty.
    23          * @return array List of URLs for a sitemap.
     23         * @return array[] Array of URL information for a sitemap.
    2424         */
    2525        public function get_url_list( $page_num, $object_subtype = '' ) {

  • trunk/tests/phpunit/includes/class-wp-sitemaps-large-test-provider.php

    r48532 r52204  
    3131         * @param int    $page_num       Page of results.
    3232         * @param string $object_subtype Optional. Object subtype name. Default empty.
    33          * @return array List of URLs for a sitemap.
     33         * @return array[] Array of URL information for a sitemap.
    3434         */
    3535        public function get_url_list( $page_num, $object_subtype = '' ) {

  • trunk/tests/phpunit/includes/class-wp-sitemaps-test-provider.php

    r48072 r52204  
    3535         * @param int    $page_num       Page of results.
    3636         * @param string $object_subtype Optional. Object subtype name. Default empty.
    37          * @return array List of URLs for a sitemap.
     37         * @return array[] Array of URL information for a sitemap.
    3838         */
    3939        public function get_url_list( $page_num, $object_subtype = '' ) {
Note: See TracChangeset for help on using the changeset viewer.