Docblock improvements for 5.4

[desrosj]

Previously:

• #47110 (5.3)
• #46543 (5.2)
• #42505 (5.1)
• #41017 (4.9)
• #39130 (4.8)
• #37770 (4.7)
• #32246 (4.6)

[marekdedic]

I didn't know about this tracking ticket for all the small docs issues, so I created a lot of small ones (sorry...)

#48343

$args documentation for WP_Customize_Control::__construct() and WP_Customize_Manager::add_control() don't match

#48344

WP_Customize_Panel::__construct() is missing `$args` documentation

#48346

WP_Customize_Section::__construct() is missing `$args` documentation

#48347

WP_Customize_Setting::__construct() is missing `$args` documentation

#48348

WP_Customize_Color_Control::__construct should link to parent constructor for $args

#48349

Requests::request_multiple() should have the option documentation in phpDoc

#48350

Stricter docs for WP_Http::processHeaders()

#48351

Stricter docs for WP_Http::processResponse()

#48352

Stricter docs for deactivate_plugins

#48353

Stricter docs for esc_url

#48354

Stricter docs for is_page() and WP_Query::is_page()

[marekdedic]

wp_enqueue_script, wp_enqueue_style, wp_register_script and wp_register_style parameter $deps could be narrowed from array to string[].

[marekdedic]

wp_unslash parameter and return value could be narrowed from string|array to string|string[].

[Marcio Zebedeu]

adding documentation > Ticket #48348

[Marcio Zebedeu]

adding documentation > Ticket #48348

[Marcio Zebedeu]

made the change from wordpress to WordPress

[SergeyBiryukov]

In 46591:

Docs: Improve formatting of various WP_Screen DocBlocks.

See #48303.

[johnbillion]

In 46594:

Docs: Miscellaneous docblock fixes and improvements.

See #48303

[johnbillion]

In 46595:

Docs: Switch to typed array notation for the docs for asset dependency functions.

Props marekdedic

See #48303

[johnbillion]

In 46596:

Docs: Switch more docs over to typed array notation, plus some fixes.

See #48303, #41756

[johnbillion]

In 46597:

Docs: Update the docs for the error parameter that gets passed around during filesystem credential collection.

See #48303

[johnbillion]

In 46598:

Docs: Add missing docs for the auth_cookie_bad_session_token action.

See #48303

[johnbillion]

In 46599:

Docs: Correct and improve inline docs for the file type functions.

See #48303

[SergeyBiryukov]

In 46600:

Docs: Improve DocBlock formatting in WP_Block_Styles_Registry per the documentation standards.

See #48303.

[johnbillion]

In 46603:

Docs: Correct invalid hook docblocks.

See #48303

[johnbillion]

In 46604:

Docs: Correct invalid hook docblock placement.

See #48303

[SergeyBiryukov]

In 46607:

Docs: Restore correct placement for duplicate hook reference in render_block_core_latest_comments().

Previously fixed in [46604], accidentally reverted in [46606].

See #48447, #48303.

[johnbillion]

In 46608:

Docs: Remove some funky nested filters.

See #48303

[johnbillion]

In 46609:

Docs: Coding standards fix after [46608].

See #48303

[johnbillion]

In 46610:

Docs: Miscellaneous docblock corrections.

See #48303

[johnbillion]

In 46623:

Docs: Correct some incorrect docblock tags.

See #48303

[johnbillion]

In 46624:

Docs: Correct some more invalid inline docs.

See ​https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/php/#summary-formerly-short-description

See #48303

[SergeyBiryukov]

In 46630:

Docs: Correct @see references for PHP 4 constructors in wp-includes/class-json.php.

See #48252, #48303.

[spenserhale]

Attached patch for #48352

[johnbillion]

In 46644:

Docs: Fix some incorrect return tags in docblocks.

See #48303

[Marcio Zebedeu]

Replying to johnbillion:

In 46644:

Docs: Fix some incorrect return tags in docblocks.

See #48303

I'll fix it.

[SergeyBiryukov]

In 46647:

Docs: Correct some array hash notations added in [46644].

See #48303.

[Marcio Zebedeu]

Corrected array hash notations

[Marcio Zebedeu]

Replying to SergeyBiryukov:

In 46647:

Docs: Correct some array hash notations added in [46644].

See #48303.

Can you please confirm? I had my doubts about naming patch.

[johnbillion]

In 46652:

Docs: Correct and improve the readability of some parameters of WP_Term_Query.

See #48303

[johnbillion]

In 46660:

Docs: Improve documentation of known return types, plus other docs fixes.

See #48303

[johnbillion]

In 46661:

Docs: Further improve documentation of known return types, plus other docs fixes.

See #48303

[johnbillion]

In 46662:

Docs: Docs on docs. Further improve documentation of known return types, plus other docs fixes.

See #48303

[SergeyBiryukov]

In 46691:

Docs: Move the @link tag for Customize API in WP_Customize_Manager::add_setting() and WP_Customize_Setting to a more appropriate place.

See #48303.

[Marcio Zebedeu]

Docs: Moved the @link tag for Customize API in WP_Customize_Manager::add_setting() and WP_Customize_Setting

[Marcio Zebedeu]

Replying to SergeyBiryukov:

In 46691:

Docs: Move the @link tag for Customize API in WP_Customize_Manager::add_setting() and WP_Customize_Setting to a more appropriate place.

See #48303.

done

[SergeyBiryukov]

Replying to Marcio Zebedeu:

Can you please confirm? I had my doubts about naming patch.

Thanks for the patches! However, [46647] and [46691] are changesets, not tasks. These are changes that are already committed and generally don't require additional patches, unless you notice a typo or any other inaccuracy :)

[Marcio Zebedeu]

Replying to SergeyBiryukov:

Replying to Marcio Zebedeu:

Can you please confirm? I had my doubts about naming patch.

Thanks for the patches! However, [46647] and [46691] are changesets, not tasks. These are changes that are already committed and generally don't require additional patches, unless you notice a typo or any other inaccuracy :)

Oh...thank. I'm still learning :)

[SergeyBiryukov]

In 46695:

Docs: Miscellaneous docblock corrections in wp-admin/includes/plugin.php.

See #48303.

[SergeyBiryukov]

In 46696:

Docs: In various @return tags, list the expected type first, instead of WP_Error.

See #48303.

[johnbillion]

In 46729:

Docs: Correct some invalid hook docblocks.

See #48303

[SergeyBiryukov]

In 46760:

Docs: Adjust wp_is_json_request() and wp_is_xml_request() return value descriptions for consistency.

See #48771, #48303.

[SergeyBiryukov]

In 46800:

Docs: Replace @returns tags in JS docs with @return.

Per the documentation standards, @returns is an unsupported synonym, @return should be used instead:
​https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/javascript/

See #48303.

[SergeyBiryukov]

In 46801:

Docs: Correct @param type for the function parameter in tests_add_filter() and _test_filter_build_unique_id().

Synchronize documentation for add_filter(), tests_add_filter(), _wp_filter_build_unique_id(), _test_filter_build_unique_id().

Add a note that $tag and $priority are no longer used in _wp_filter_build_unique_id() since [46220], and the function always returns a string now.

Props donmhico, remcotolsma, SergeyBiryukov.
Fixes #47407. See #48303.

[johnbillion]

In 46821:

Docs: Correct various docblocks documentation.

See #48303

[johnbillion]

In 46823:

Docs: Increase the specificity of various docblock parameter types and return types.

See #48303

[johnbillion]

In 46826:

Docs: Further docblock corrections and improvements.

See #48303

[SergeyBiryukov]

In 46827:

Bundled Themes: Correct @since tags to refer to the theme version instead of WordPress version.

This makes @since notations in Twenty Seventeen, Twenty Nineteen, and Twenty Twenty consistent with the previous bundled themes.

See #48303.

[SergeyBiryukov]

In 46828:

Twenty Twenty: Use duplicate hook references for page_css_class and page_menu_link_attributes filters in TwentyTwenty_Walker_Page.

See #48303.

[SergeyBiryukov]

In 46837:

Docs: Correct DocBlock formatting for admin_email_confirm and admin_email_confirm_form hooks.

See #48303.

[SergeyBiryukov]

In 46882:

Tests: Docs: Correct @param formatting in SpeedTrapListener after [35226] and [45607].

See #48303.

[SergeyBiryukov]

In 46985:

Docs: Various documentation fixes for unit test factories.

See #48303.

[SergeyBiryukov]

In 46986:

Docs: Add @method notation for WP_UnitTest_Factory_For_Term::create_and_get() for consistency with other factories.

See #48303.

[SergeyBiryukov]

In 46987:

Docs: Improve comments in tests/formatting/redirect.php per the documentation standards.

See #48303.

[SergeyBiryukov]

In 47009:

Docs: Use a third-person singular verb for comment template function descriptions, per the documentation standards.

See #48303.

[SergeyBiryukov]

In 47017:

Docs: Improve @return description for wp_update_comment() and WP_UnitTest_Factory_For_Comment::update_object().

See #48303.

[SergeyBiryukov]

In 47022:

Docs: Add missing @since tags for wp-includes/class-wp-editor.php.

See #48303.

[SergeyBiryukov]

In 47032:

Docs: Synchronize "Default empty array" notes for $args parameter in get_comment_text() and comment_text().

Props denisco.
See #48303.

[ocean90]

In 47042:

Docs: Remove duplicate inline comment in wp_mail().

See [5639].
See #48303.

[SergeyBiryukov]

In 47049:

Docs: Indicate that load_script_textdomain_relative_path filter value can be false.

See #48303.

[SergeyBiryukov]

In 47052:

Docs: Correct alphabetic order of parameters in WP_Query::parse_query() DocBlock.

See #48303.

[SergeyBiryukov]

In 47055:

Docs: Remove @return void from widget DocBlocks.

Per the documentation standards, it should not be used outside of the default bundled themes.

See #48303.

[SergeyBiryukov]

In 47059:

Docs: Synchronize @return descriptions for ::handle_row_actions() methods in list tables.

Make sure WP_Comments_List_Table::handle_row_actions() and WP_MS_Sites_List_Table::handle_row_actions() return a string, for consistency with other classes.

See #49170, #48303.

[SergeyBiryukov]

In 47060:

Docs: In various @return tags, list the expected type first, instead of false.

Follow-up to [46696].

See #48303.

[SergeyBiryukov]

In 47065:

Docs: Improve documentation for wp_save_image_file() and related functions.

See #48303.

[SergeyBiryukov]

In 47088:

Docs: Update links to ​https://secure.php.net/, they now redirect to ​https://www.php.net/.

See #48303.

[SergeyBiryukov]

In 47096:

Docs: Correct DocBlock formatting for filters accepting the $parsed_args parameter.

Follow-up to [45667].

See #48303.

[SergeyBiryukov]

In 47097:

Docs: Expand @return value description for wp_nav_menu().

See #48303.

[SergeyBiryukov]

In 47099:

Docs: Correct @return value for update_core() and Core_Upgrader::upgrade().

See #48303.

[SergeyBiryukov]

In 47100:

Docs: Adjust @return value of parent_dropdown() for consistency with other dropdown functions.

See #48303.

[SergeyBiryukov]

In 47101:

Docs: Adjust documentation for some pre_* filters for consistency.

See #48303.

[SergeyBiryukov]

In 47102:

Docs: Correct @return value for parent_dropdown().

Follow-up to [47100].

See #48303.

[SergeyBiryukov]

In 47103:

Docs: Expand @return description for the_terms().

See #48303.

[SergeyBiryukov]

In 47104:

Docs: Expand @return value description for wp_loginout(), wp_register(), get_calendar().

See #48303.

[marekdedic]

Hi, I started by looking at the function get_the_post_thumbnail and its parameter $size, which is currently of the type string|array. I think this could be narrowed down to string|int[] by examining its source and all the functions and hooks it calls. As such, I think these functions and hooks could have their parameter $size narrowed in the same way. The ones I encountered:

Functions:

• get_the_post_thumbnail
• wp_get_attachment_image
• wp_get_attachment_image_src
• image_downsize
• image_get_intermediate_size
• image_constrain_size_for_editor

Hooks:

• begin_fetch_post_thumbnail_html
• end_fetch_post_thumbnail_html
• wp_get_attachment_image_src
• image_downsize
• image_get_intermediate_size
• editor_max_image_size

However, I'm pretty sure there are more.

[SergeyBiryukov]

In 47109:

Docs: Improve documentation for add_user_to_blog(), add_existing_user_to_blog(), and add_new_user_to_blog().

See #48303.

[johnbillion]

@marekdedic Thanks for the comment, I think this is covered by #47364.

[marekdedic]

Hi, OK, thanks.

6 more functions that can have parameters narrowed:

• is_page can have parameter narrowed to int|string|int[]|string[]
• is_single can have parameter narrowed to int|string|int[]|string[]
• is_singular can have parameter narrowed to string|string[]
• WP_Query::is_page can have parameter narrowed to int|string|int[]|string[]
• WP_Query::is_single can have parameter narrowed to int|string|int[]|string[]
• WP_Query::is_singular can have parameter narrowed to string|string[]

Partially covered by #48354

[SergeyBiryukov]

In 47121:

Docs: Improve DocBlocks in phpunit/includes/object-cache.php per the documentation standards.

See #48303.

[SergeyBiryukov]

In 47122:

Docs: Improve inline comments per the documentation standards.

Includes minor code layout fixes for better readability.

See #48303.

[SergeyBiryukov]

In 47157:

Docs: Correct DocBlock formatting for register_setting().

Document the full list of whitelisted option key names.

See #48303.

[SergeyBiryukov]

In 47159:

Docs: Improve inline comments in wp-admin/options.php per the documentation standards.

See #48303.

[SergeyBiryukov]

In 47165:

Docs: Fix typo in a comment with WP_DEBUG_DISPLAY description.

See #48303.

[SergeyBiryukov]

In 47170:

Docs: Improve documentation for WP_Dependencies, WP_Scripts, and WP_Styles methods.

See #48303.

[SergeyBiryukov]

In 47174:

Docs: Improve description for add_user_to_blog() and remove_user_from_blog() parameters.

See #48303.

[SergeyBiryukov]

In 47189:

Docs: Correct type for $item and $args parameters in Walker_Nav_Menu_Checklist and Walker_Nav_Menu_Edit to match the parent Walker_Nav_Menu` class.

Follow-up to [38559], [45537].

See #24587, #48303.

[SergeyBiryukov]

In 47230:

Docs: Add descriptions for some globals:

• $wp_version
• $wp_local_package
• $required_php_version
• $required_mysql_version

See #48303.

[SergeyBiryukov]

In 47295:

Docs: Improve inline comments for require_once() calls in WP_REST_Attachments_Controller.

See #49449, #48303.

[SergeyBiryukov]

In 47297:

Docs: Fix typo in a comment in WP_REST_Attachments_Controller::create_item().

See #48303.

[SergeyBiryukov]

In 47298:

Docs: Improve inline comments for require_once calls in WP_REST_Users_Controller per the documentation standards.

Follow-up to [47295].

See #48303.

[SergeyBiryukov]

In 47347:

Docs: Use third-person singular verbs for function descriptions in wp-includes/option.php, per the documentation standards.

See #48303.

[SergeyBiryukov]

In 47383:

Docs: Use a consistent description for the $manager parameter in various Customizer class constructions.

See #48303.

[johnbillion]

In 47394:

Docs: Correct and improve the docs for some media related functions.

See #48303

[johnbillion]

In 47396:

Docs: Correct the parameter documentation of the request_filesystem_credentials filter.

See #48303

[johnbillion]

In 47397:

Docs: Use more specific types in parameter descriptions in place of mixed.

See #48303.

[johnbillion]

In 47398:

Docs: Miscellaneous docs fixes and improvements.

See #48303.

[SergeyBiryukov]

In 47399:

Docs: Use more specific type in description for _WP_Dependency::$deps.

Props marekdedic.
See #48303.

[SergeyBiryukov]

In 47400:

Docs: Use more specific type in parameter description for wp_unslash().

Props marekdedic.
See #48303.

[SergeyBiryukov]

In 47401:

Docs: Synchronize parameter descriptions for conditional tags with their WP_Query counterpart methods.

See #48354, #48303.

[SergeyBiryukov]

In 47402:

Docs: Use more specific type in parameter descriptions for is_page(), is_single(), is_singular(), and their WP_Query counterpart methods.

Props marekdedic, shaharia.azam, shaampk1.
Fixes #48354. See #48303.

[SergeyBiryukov]

Replying to johnbillion:

In 47394:

Docs: Correct and improve the docs for some media related functions.

See #48303

@johnbillion I can't seem to figure out when the first parameter of the image_downsize filter can be an array. The filter is used in two places, and both pass false as the first parameter. Was the change to bool|array intentional?

wp_image_resize_identical_dimensions uses a similar approach, and the first parameter is still documented as bool there.

[johnbillion]

@SergeyBiryukov It can be an array if another filter is filtering the value and returning an array intended as the short-circuited return value.

Good point though - Core is not consistent in documenting the types for these short-circuit filter parameters. Worth a separate ticket?

[SergeyBiryukov]

Replying to johnbillion:

It can be an array if another filter is filtering the value and returning an array intended as the short-circuited return value.

Indeed, thanks! That could be clarified in the description though.

Good point though - Core is not consistent in documenting the types for these short-circuit filter parameters. Worth a separate ticket?

Probably :) With 5.4 RC1 approaching, let's close this one as fixed.

[SergeyBiryukov]

Follow-up: #49572

[westonruter]

@SergeyBiryukov Just saw the changes here and I'm getting static analysis warnings for code like:

<?php
wp_scripts()->add_data(
        $handle,
        'foo_script_attributes',
        [
                'async' => true,
        ]
);

This ​change to WP_Dependencies::add_data() in r47170 appears to not be correct:

-        * @param mixed  $value  The data value.
+        * @param string $value  The data value.

It has a mismatch with wp_script_add_data() which still indicates the type of $value as being mixed.

[SergeyBiryukov]

Replying to westonruter:

This ​change to WP_Dependencies::add_data() in r47170 appears to not be correct:

-        * @param mixed  $value  The data value.
+        * @param string $value  The data value.

It has a mismatch with wp_script_add_data() which still indicates the type of $value as being mixed.

Thanks for catching that! I guess I was confused by the fact that while the parameter indeed has a mixed type, it's described as a string in several places:

• "Extra item data (string)" in WP_Dependencies::get_data().
• "String containing the data to be added" in wp_script_add_data().
• "String containing the CSS data to be added" in wp_style_add_data().

Let's revert that change for now and clean up the inconsistencies later.

[SergeyBiryukov]

In 47502:

Docs: Revert a type change for the $value parameter of WP_Dependencies::add_data() in [47170].

Although described as a string in several places, it's technically not limited to a particular type.

Props westonruter.
See #48303.

[SergeyBiryukov]

In 47503:

Docs: Revert a type change for the $value parameter of WP_Dependencies::add_data() in [47170].

Although described as a string in several places, it's technically not limited to a particular type.

Props westonruter.
Reviewed by jorgefilipecosta, SergeyBiryukov.
Merges [47502] to the 5.4 branch.
Fixes #48303.

[SergeyBiryukov]

Replying to SergeyBiryukov:

Let's revert that change for now and clean up the inconsistencies later.

Left a comment on #49572 as a follow-up: comment:4:ticket:49572.