WordPress.org

Make WordPress Core

Changeset 52204


Ignore:
Timestamp:
11/18/2021 01:48:43 PM (2 months 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.