WordPress.org

Make WordPress Core

Opened 6 months ago

Closed 2 weeks ago

Last modified 2 weeks ago

#48303 closed task (blessed) (fixed)

Docblock improvements for 5.4

Reported by: desrosj Owned by: SergeyBiryukov
Milestone: 5.4 Priority: normal
Severity: normal Version:
Component: General Keywords:
Focuses: docs Cc:

Description

Previously:

Attachments (6)

48348.patch (5.9 KB) - added by Marcio Zebedeu 6 months ago.
adding documentation > Ticket #48348
48348.1.patch (6.1 KB) - added by Marcio Zebedeu 6 months ago.
adding documentation > Ticket #48348
48417.patch (2.4 KB) - added by Marcio Zebedeu 6 months ago.
made the change from wordpress to WordPress
48352.patch (789 bytes) - added by spenserhale 5 months ago.
46644.patch (1.1 KB) - added by Marcio Zebedeu 5 months ago.
Corrected array hash notations
46691.patch (1.5 KB) - added by Marcio Zebedeu 5 months ago.
Docs: Moved the @link tag for Customize API in WP_Customize_Manager::add_setting() and WP_Customize_Setting

Download all attachments as: .zip

Change History (112)

#1 @marekdedic
6 months ago

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()


Last edited 6 months ago by SergeyBiryukov (previous) (diff)

#2 @marekdedic
6 months ago

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

Last edited 6 months ago by marekdedic (previous) (diff)

#3 @marekdedic
6 months ago

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

@Marcio Zebedeu
6 months ago

adding documentation > Ticket #48348

@Marcio Zebedeu
6 months ago

adding documentation > Ticket #48348

@Marcio Zebedeu
6 months ago

made the change from wordpress to WordPress

#4 @SergeyBiryukov
6 months ago

In 46591:

Docs: Improve formatting of various WP_Screen DocBlocks.

See #48303.

#5 @johnbillion
6 months ago

In 46594:

Docs: Miscellaneous docblock fixes and improvements.

See #48303

#6 @johnbillion
6 months ago

In 46595:

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

Props marekdedic

See #48303

#7 @johnbillion
6 months ago

In 46596:

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

See #48303, #41756

#8 @johnbillion
6 months ago

In 46597:

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

See #48303

#9 @johnbillion
6 months ago

In 46598:

Docs: Add missing docs for the auth_cookie_bad_session_token action.

See #48303

#10 @johnbillion
6 months ago

In 46599:

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

See #48303

#11 @SergeyBiryukov
6 months ago

In 46600:

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

See #48303.

#12 @johnbillion
6 months ago

In 46603:

Docs: Correct invalid hook docblocks.

See #48303

#13 @johnbillion
6 months ago

In 46604:

Docs: Correct invalid hook docblock placement.

See #48303

#14 @SergeyBiryukov
6 months ago

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.

This ticket was mentioned in Slack in #docs by atachibana. View the logs.


5 months ago

#16 @johnbillion
5 months ago

In 46608:

Docs: Remove some funky nested filters.

See #48303

#17 @johnbillion
5 months ago

In 46609:

Docs: Coding standards fix after [46608].

See #48303

#18 @johnbillion
5 months ago

In 46610:

Docs: Miscellaneous docblock corrections.

See #48303

#19 @johnbillion
5 months ago

In 46623:

Docs: Correct some incorrect docblock tags.

See #48303

#21 @SergeyBiryukov
5 months ago

In 46630:

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

See #48252, #48303.

@spenserhale
5 months ago

#22 @spenserhale
5 months ago

Attached patch for #48352

#23 follow-up: @johnbillion
5 months ago

In 46644:

Docs: Fix some incorrect return tags in docblocks.

See #48303

#24 in reply to: ↑ 23 @Marcio Zebedeu
5 months ago

Replying to johnbillion:

In 46644:

Docs: Fix some incorrect return tags in docblocks.

See #48303

I'll fix it.

#25 follow-up: @SergeyBiryukov
5 months ago

In 46647:

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

See #48303.

@Marcio Zebedeu
5 months ago

Corrected array hash notations

#26 in reply to: ↑ 25 ; follow-up: @Marcio Zebedeu
5 months ago

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.

#27 @johnbillion
5 months ago

In 46652:

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

See #48303

#28 @johnbillion
5 months ago

In 46660:

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

See #48303

#29 @johnbillion
5 months ago

In 46661:

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

See #48303

#30 @johnbillion
5 months ago

In 46662:

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

See #48303

#31 follow-up: @SergeyBiryukov
5 months ago

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
5 months ago

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

#32 in reply to: ↑ 31 @Marcio Zebedeu
5 months ago

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

#33 in reply to: ↑ 26 ; follow-up: @SergeyBiryukov
5 months ago

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 :)

#34 in reply to: ↑ 33 @Marcio Zebedeu
5 months ago

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 :)

#35 @SergeyBiryukov
5 months ago

In 46695:

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

See #48303.

#36 @SergeyBiryukov
5 months ago

In 46696:

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

See #48303.

#37 @johnbillion
5 months ago

In 46729:

Docs: Correct some invalid hook docblocks.

See #48303

#38 @SergeyBiryukov
5 months ago

In 46760:

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

See #48771, #48303.

#39 @SergeyBiryukov
4 months ago

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.

#40 @SergeyBiryukov
4 months ago

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.

#41 @johnbillion
4 months ago

In 46821:

Docs: Correct various docblocks documentation.

See #48303

#42 @johnbillion
4 months ago

In 46823:

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

See #48303

#43 @johnbillion
4 months ago

In 46826:

Docs: Further docblock corrections and improvements.

See #48303

#44 @SergeyBiryukov
4 months ago

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.

#45 @SergeyBiryukov
4 months ago

In 46828:

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

See #48303.

#46 @SergeyBiryukov
4 months ago

In 46837:

Docs: Correct DocBlock formatting for admin_email_confirm and admin_email_confirm_form hooks.

See #48303.

#47 @SergeyBiryukov
4 months ago

In 46882:

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

See #48303.

#48 @SergeyBiryukov
4 months ago

In 46985:

Docs: Various documentation fixes for unit test factories.

See #48303.

#49 @SergeyBiryukov
4 months ago

In 46986:

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

See #48303.

#50 @SergeyBiryukov
4 months ago

In 46987:

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

See #48303.

#51 @SergeyBiryukov
4 months ago

In 47009:

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

See #48303.

#52 @SergeyBiryukov
4 months ago

In 47017:

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

See #48303.

#53 @SergeyBiryukov
3 months ago

In 47022:

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

See #48303.

#54 @SergeyBiryukov
3 months ago

In 47032:

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

Props denisco.
See #48303.

#55 @ocean90
3 months ago

In 47042:

Docs: Remove duplicate inline comment in wp_mail().

See [5639].
See #48303.

#56 @SergeyBiryukov
3 months ago

In 47049:

Docs: Indicate that load_script_textdomain_relative_path filter value can be false.

See #48303.

#57 @SergeyBiryukov
3 months ago

In 47052:

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

See #48303.

#58 @SergeyBiryukov
3 months ago

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.

#59 @SergeyBiryukov
3 months ago

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.

#60 @SergeyBiryukov
3 months ago

In 47060:

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

Follow-up to [46696].

See #48303.

#61 @SergeyBiryukov
3 months ago

In 47065:

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

See #48303.

#62 @SergeyBiryukov
3 months ago

In 47088:

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

See #48303.

#63 @SergeyBiryukov
3 months ago

In 47096:

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

Follow-up to [45667].

See #48303.

#64 @SergeyBiryukov
3 months ago

In 47097:

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

See #48303.

#65 @SergeyBiryukov
3 months ago

In 47099:

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

See #48303.

#66 @SergeyBiryukov
3 months ago

In 47100:

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

See #48303.

#67 @SergeyBiryukov
3 months ago

In 47101:

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

See #48303.

#68 @SergeyBiryukov
3 months ago

In 47102:

Docs: Correct @return value for parent_dropdown().

Follow-up to [47100].

See #48303.

#69 @SergeyBiryukov
3 months ago

In 47103:

Docs: Expand @return description for the_terms().

See #48303.

#70 @SergeyBiryukov
3 months ago

In 47104:

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

See #48303.

#71 @marekdedic
3 months ago

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.

#72 @SergeyBiryukov
3 months ago

In 47109:

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

See #48303.

#73 @johnbillion
3 months ago

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

#74 @marekdedic
2 months ago

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

#75 @SergeyBiryukov
2 months ago

In 47121:

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

See #48303.

#76 @SergeyBiryukov
2 months ago

In 47122:

Docs: Improve inline comments per the documentation standards.

Includes minor code layout fixes for better readability.

See #48303.

#77 @SergeyBiryukov
2 months ago

In 47157:

Docs: Correct DocBlock formatting for register_setting().

Document the full list of whitelisted option key names.

See #48303.

#78 @SergeyBiryukov
2 months ago

In 47159:

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

See #48303.

#79 @SergeyBiryukov
2 months ago

In 47165:

Docs: Fix typo in a comment with WP_DEBUG_DISPLAY description.

See #48303.

#80 @SergeyBiryukov
2 months ago

In 47170:

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

See #48303.

#81 @SergeyBiryukov
2 months ago

In 47174:

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

See #48303.

#82 @SergeyBiryukov
2 months ago

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.

#83 @SergeyBiryukov
2 months ago

In 47230:

Docs: Add descriptions for some globals:

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

See #48303.

#84 @SergeyBiryukov
8 weeks ago

In 47295:

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

See #49449, #48303.

#85 @SergeyBiryukov
8 weeks ago

In 47297:

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

See #48303.

#86 @SergeyBiryukov
8 weeks ago

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.

#87 @SergeyBiryukov
7 weeks ago

In 47347:

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

See #48303.

#88 @SergeyBiryukov
6 weeks ago

In 47383:

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

See #48303.

#89 follow-up: @johnbillion
6 weeks ago

In 47394:

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

See #48303

#90 @johnbillion
6 weeks ago

In 47396:

Docs: Correct the parameter documentation of the request_filesystem_credentials filter.

See #48303

#91 @johnbillion
6 weeks ago

In 47397:

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

See #48303.

#92 @johnbillion
6 weeks ago

In 47398:

Docs: Miscellaneous docs fixes and improvements.

See #48303.

#93 @SergeyBiryukov
6 weeks ago

In 47399:

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

Props marekdedic.
See #48303.

#94 @SergeyBiryukov
6 weeks ago

In 47400:

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

Props marekdedic.
See #48303.

#95 @SergeyBiryukov
6 weeks ago

In 47401:

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

See #48354, #48303.

#96 @SergeyBiryukov
6 weeks ago

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.

#97 in reply to: ↑ 89 @SergeyBiryukov
6 weeks ago

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.

#98 follow-up: @johnbillion
6 weeks ago

@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?

#99 in reply to: ↑ 98 @SergeyBiryukov
5 weeks ago

  • Resolution set to fixed
  • Status changed from new to closed

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.

#101 follow-up: @westonruter
3 weeks ago

@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.

#102 @SergeyBiryukov
3 weeks ago

  • Resolution fixed deleted
  • Status changed from closed to reopened

#103 in reply to: ↑ 101 ; follow-up: @SergeyBiryukov
2 weeks ago

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.

Last edited 2 weeks ago by SergeyBiryukov (previous) (diff)

#104 @SergeyBiryukov
2 weeks ago

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.

#105 @SergeyBiryukov
2 weeks ago

  • Owner set to SergeyBiryukov
  • Resolution set to fixed
  • Status changed from reopened to closed

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.

#106 in reply to: ↑ 103 @SergeyBiryukov
2 weeks ago

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.

Note: See TracTickets for help on using tickets.