Make WordPress Core

Opened 3 years ago

Closed 2 years ago

Last modified 12 months ago

#53399 closed task (blessed) (fixed)

Docblock improvements for WP 5.9

Reported by: desrosj's profile desrosj Owned by:
Milestone: 5.9 Priority: normal
Severity: normal Version:
Component: General Keywords: has-patch has-unit-tests
Focuses: docs Cc:

Description

Previously:

Attachments (2)

53399.internal.diff (1.1 KB) - added by SergeyBiryukov 3 years ago.
53399-adminbar-docblocks.diff (8.0 KB) - added by audrasjb 2 years ago.
Docs: Toolbar: Miscellaneous docblock corrections and improvements.

Download all attachments as: .zip

Change History (136)

#1 @SergeyBiryukov
3 years ago

In 51278:

Docs: Document the globals used in some REST API methods.

See #53399.

#2 @johnbillion
3 years ago

In 51297:

Docs: Fix the documentation for the $tests parameter of the site_status_tests filter.

Tests are contained within direct and async properties of this array, not directly in the array itself. This also clarifies the properties that differ between direct and async tests.

See #53399, #46573

#3 @johnbillion
3 years ago

In 51298:

Docs: Corrections and improvements to types used in docblocks for symbols, properties, and filters.

See #53399

#4 @johnbillion
3 years ago

In 51299:

Docs: Miscellaneous formatting corrections for docblocks.

See #53399

#5 @johnbillion
3 years ago

In 51300:

Docs: Descriptive improvements and corrections for various docblocks.

See #53399

#6 @SergeyBiryukov
3 years ago

Looks like [51300] accidentally reverted [51299].

#7 @johnbillion
3 years ago

In 51301:

Docs: Undo the accidental revert of [51299] made in [51300].

See #53399

#8 @johnbillion
3 years ago

In 51302:

Docs: Further type corrections and improvements for various docblocks.

See #53399

#9 @SergeyBiryukov
3 years ago

In 51303:

Docs: Correct description for the $image parameter of the wp_save_image_file filter.

Follow-up to [27357], [48798], [51302].

See #53399.

#10 @SergeyBiryukov
3 years ago

In 51328:

Docs: Add @since tags for WP_Theme class properties.

Document WordPress versions Twenty Twelve and later bundled themes were introduced in.

See #53399.

#11 @johnbillion
3 years ago

In 51330:

Docs: Miscellaneous docblock improvements.

See #53399

#12 @SergeyBiryukov
3 years ago

In 51425:

Docs: Correct documentation for wp_get_post_parent_id().

The $post parameter is required and does not have a default value.

Follow-up to [42397].

Props denisco.
See #53399.

#13 @SergeyBiryukov
3 years ago

In 51430:

Docs: Synchronize the $post_id argument description for some post and attachment functions.

See #53399.

#14 @johnbillion
3 years ago

In 51477:

Docs: Miscellaneous docblock corrections and improvements.

See #53399

#15 follow-up: @SergeyBiryukov
3 years ago

@johnbillion Removing @global tags for $wp_local_package and $wp_locale in setup_config_display_header() doesn't seem correct, they are both used further in the function.

Should we perhaps declare them explicitly instead of accessing via the $GLOBALS array?

#16 in reply to: ↑ 15 ; follow-up: @johnbillion
3 years ago

Replying to SergeyBiryukov:

they are both used further in the function

They actually fall outside of the function, which ends a few lines above. I didn't check but I suspect that's the original intention of those docs.

#17 in reply to: ↑ 16 @SergeyBiryukov
3 years ago

Replying to johnbillion:

They actually fall outside of the function, which ends a few lines above.

Ah, yes, you're right. The docs were added in [32642], apparently due to a similar mistake that I made.

#18 @SergeyBiryukov
3 years ago

In 51495:

Docs: Clarify the @return value for WP_Filesystem_Base::getnumchmodfromh().

Follow-up to [9117], [51494].

See #53399.

#19 @johnbillion
3 years ago

In 51513:

Docs: Correct the documented allowed range for the minute and second parameters of WP_Query.

These are correctly documented and validated in WP_Date_Query as 0-59.

See #53399

#20 @johnbillion
3 years ago

In 51514:

Docs: Add missing documentation for the minute parameter of WP_Query.

See #53399

#21 @SergeyBiryukov
3 years ago

In 51527:

Docs: Fix typo in the WP_Upgrader::install_package() description.

Follow-up to [30758].

See #53399.

#22 @johnbillion
3 years ago

In 51578:

Themes: Correct the documented types for theme mod values.

A theme mod value can be of any type, not just a string.

See #53399

#23 @SergeyBiryukov
3 years ago

In 51589:

Docs: Add a @see reference to the wp_mail_content_type filter in wp_staticize_emoji_for_email().

Follow-up to [31860].

See #53399.

#24 @SergeyBiryukov
3 years ago

In 51590:

Docs: Add a @see reference to the xmlrpc_enabled filter in wp_xmlrpc_server::set_is_enabled().

Follow-up to [28065].

See #53399.

#25 @SergeyBiryukov
3 years ago

In 51592:

Docs: Improve documentation for a few functions per the documentation standards.

This affects:

  • checked()
  • selected()
  • disabled()
  • wp_readonly()
  • readonly()
  • __checked_selected_helper()

Follow-up to [143], [560], [9053], [10662], [13658], [41728], [51586].

See #53399.

#26 @SergeyBiryukov
3 years ago

In 51609:

Docs: Correct @since version for the wp_parse_str filter.

The filter was introduced along with the wp_parse_str() function in WordPress 2.2.1.

Follow-up to [5709], [8662], [26485].

See #53399.

#27 follow-up: @SergeyBiryukov
3 years ago

53399.internal.diff converts two @internal notes in wp-includes/ms-load.php to @since tags.

This would be more consistent with other similar @since notes in core:

  • the_author_posts_link():
    @since 4.4.0 Converted into a wrapper for get_the_author_posts_link()
    
  • date_i18n():
    @since 5.3.0 Converted into a wrapper for wp_date().
    
  • language_attributes():
    @since 4.3.0 Converted into a wrapper for get_language_attributes().
    
  • WP_REST_Server::error_to_response()
    @since 5.7.0 Converted to a wrapper of {@see rest_convert_error_to_response()}.
    

This would be a follow-up to [34099] and [38515]. However, I noticed that it reverts a part of [38201].

@johnbillion Do you have a preference here? Perhaps the notes above should be converted to @internal instead?

#28 @SergeyBiryukov
3 years ago

In 51654:

Docs: Clarify a comment in WP_Upgrader::run().

This matches the WP_Upgrader::download_package() documentation more closely.

Follow-up to [11005], [30758], [33685].

See #53399.

#29 @SergeyBiryukov
3 years ago

In 51655:

Docs: Add missing @since tag for the $check_signatures parameter of WP_Upgrader::run().

This matches the WP_Upgrader::download_package() documentation more closely.

Follow-up to [44954], [45262].

See #53399.

#30 @SergeyBiryukov
3 years ago

In 51730:

Docs: Fix typo in a comment in WP_Customize_Manager::get_return_url().

Follow-up to [46754].

See #53399.

#31 in reply to: ↑ 27 ; follow-up: @johnbillion
3 years ago

Replying to SergeyBiryukov:

Do you have a preference here? Perhaps the notes above should be converted to @internal instead?

@SergeyBiryukov To be honest I don't think these comments provide value to a developer. Whether or not a function internally wraps another one is of no consequence if it doesn't affect its external API. I'd be in favour of removing them.

#32 in reply to: ↑ 31 @SergeyBiryukov
3 years ago

Replying to johnbillion:

To be honest I don't think these comments provide value to a developer. Whether or not a function internally wraps another one is of no consequence if it doesn't affect its external API. I'd be in favour of removing them.

I think this falls under the last point in @since Section (Changelogs):

If significant changes have been made to a function, hook, class, or method, additional @since tags, versions, and descriptions should be added to provide a changelog for that function.

“Significant changes” include but are not limited to:

  • Adding new arguments or parameters
  • Required arguments becoming optional
  • Changing default/expected behaviors
  • Functions or methods becoming wrappers for new APIs

Personally, I see some value in being able to tell if there is another function that can be used as a suitable replacement, and in which version the change was made.

#33 @johnbillion
3 years ago

Good point. Let's switch them back to @since and improve the wording.

#34 @johnjamesjacoby
2 years ago

In 51827:

Docs: Remove deprecated option groups from register_setting() and add_option_update_handler().

  • misc was deprecated in version 3.0.0.
  • privacy was deprecated in version 3.5.0.

See #53399.

#35 @SergeyBiryukov
2 years ago

In 51832:

Docs: Add @since notes to register_setting() for the deprecated misc and privacy option groups.

Follow-up to [13745], [13746], [13749], [21838], [51827].

See #53399.

#36 @johnbillion
2 years ago

In 51851:

Docs: Miscellaneous docblock corrections and improvements.

See #52217, #53399

@audrasjb
2 years ago

Docs: Toolbar: Miscellaneous docblock corrections and improvements.

#37 @audrasjb
2 years ago

While I was working on a ticket related to the Admin Toolbar, I spotted a bunch of inconsistencies. I added a small patch to fix them, feel free to use it if needed :)

#38 @johnbillion
2 years ago

In 51885:

Docs: Miscellaneous inline documentation improvements, including:

  • Document the post statuses global as an array of stdClass objects
  • Document the taxonomies global as an array of WP_Taxonomy objects
  • Document the return value of the post count functions as stdClass objects
  • Fix some typos

See #53399

#39 @johnbillion
2 years ago

In 51886:

Docs: Improve various inline documentation for admin bar functions and hooks.

Props audrasjb

See #53399

#40 @johnbillion
2 years ago

In 51915:

REST API: Correct the order of the parameters documented for WP_REST_Server::respond_to_request().

See #53399

#41 @peterwilsoncc
2 years ago

In 51930:

Docs: Use sign-up & signup consistently in wp-signup.php.

In the docblocks throughout wp-signup.php use sign up for verbs and sign-up for nouns.

Props audrasjb, jeffpaul.
Fixes #54041. See #53399.

#42 @SergeyBiryukov
2 years ago

In 51942:

Docs: Document the usage of some globals in wp-includes/script-loader.php.

Follow-up to [44114], [44262], [49080], [50761], [51471].

See #53399.

#43 @johnbillion
2 years ago

In 51949:

Site Health: Correct and improve the documentation for the debug_information hook.

This corrects the structure of the documentation so it accurately reflects the array elements contained within.

See #53399.

#44 @johnbillion
2 years ago

In 51950:

Date/Time: Improve the docblocks for various date and time related functions.

See #53399, #28992, #40653

#45 @johnbillion
2 years ago

In 51955:

Docs: Miscellaneous docblock improvements.

See #53399

#46 @SergeyBiryukov
2 years ago

In 51956:

Docs: Further update the debug_information filter description per the documentation standards.

Specifically, this ensures that the DocBlock follows the line wrapping recommendations.

Follow-up to [44986], [45156], [45259], [51949].

See #53399.

#47 @johnbillion
2 years ago

In 51957:

Docs: Miscellaneous docblock improvements.

See #53399

#48 @johnbillion
2 years ago

In 51958:

Application Passwords: Various docblock improvements.

See #53399, #42790

#49 @SergeyBiryukov
2 years ago

In 51961:

Docs: Add a @since note to WP_REST_Post_Types_Controller::get_item_schema() for the supports and visibility properties.

The taxonomies and rest_base properties were also added after the method was initially introduced, but that happened during the same release cycle, so they don't need a separate @since note.

Follow-up to [38832], [39097], [39191], [39647], [51959].

See #53399.

#50 @SergeyBiryukov
2 years ago

In 51965:

Docs: Add a @since note for the rest_namespace argument of register_post_type() and register_taxonomy().

Use 3-digit, x.x.x-style semantic versioning for @since tags of the $rest_namespace property in WP_Post_Type and WP_Taxonomy.

Add a @since note to WP_REST_Taxonomies_Controller::get_item_schema() for the visibility and rest_namespace properties.

The rest_base property was also added after the method was initially introduced, but that happened during the same release cycle, so it doesn't need a separate @since note.

Follow-up to [38832], [39191], [42729], [51959], [51961], [51962], [51964].

See #53399.

This ticket was mentioned in Slack in #core by sergey. View the logs.


2 years ago

#52 @johnbillion
2 years ago

In 52034:

Docs: Fix some docblock syntax errors and add a missing canonical reference.

See #53399, #52867, #38942, #53668

#53 @johnbillion
2 years ago

In 52035:

Docs: Various docblock improvements and corrections.

See #53399

#54 @ocean90
2 years ago

In 52072:

Editor, Docs: Add documentation for the $block_editor_context parameter of the block_editor_rest_api_preload_paths hook.

See #52920.
See #53399.

#55 @desrosj
2 years ago

In 52110:

Docs: Avoid using “CPT” instead of “custom post type”.

Additionally, when referring to built in Core post types, “custom” is unnecessary.

This also adds a period to the end of the wp_global_styles post type description.

Follow up to [38829], [51003], [52041], [52049], [52062].

See #53399, #54335, #54336.

#56 @SergeyBiryukov
2 years ago

In 52111:

Docs: List the expected return type first in a few functions:

  • get_previous_post()
  • get_next_post()
  • get_adjacent_post().

Follow-up to [46696], [47060], [49929], [49963], [51286].

See #53399.

#57 @johnbillion
2 years ago

In 52127:

Docs: Add missing documentation for the $javascript parameter of the wp_inline_script_attributes filter.

See #53399

This ticket was mentioned in PR #1886 on WordPress/wordpress-develop by audrasjb.


2 years ago
#58

  • Keywords has-patch added

#59 @audrasjb
2 years ago

Hi,
I added a PR for a small DocBlock change.
We have to props @andy-schmidt who suggested this change on DevHub User Notes :)

This ticket was mentioned in PR #1910 on WordPress/wordpress-develop by johnbillion.


2 years ago
#60

  • Keywords has-unit-tests added

Trac ticket: https://core.trac.wordpress.org/ticket/53399

If you're interested, these were all detected by the ongoing work on the phpstan-wordpress library in https://github.com/szepeviktor/phpstan-wordpress/pull/78 .

This ticket was mentioned in PR #1911 on WordPress/wordpress-develop by johnbillion.


2 years ago
#61

Trac ticket: https://core.trac.wordpress.org/ticket/53399

Corrections to the documented type for comment ID and site ID properties.

#62 @johnbillion
2 years ago

In 52204:

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

See #53399

#63 @johnbillion
2 years ago

In 52205:

Docs: Corrections relating to types used in inline documentation for comment ID and site ID proprties.

Includes a correction for a typo introduced in [52204].

See #53399

#67 @audrasjb
2 years ago

In 52208:

Docs: Add missing null allowed type for the $id parameter of wp_set_current_user().

Props andy-schmidt.
See #53399.

#69 @desrosj
2 years ago

In 52219:

Docs: Improve the documentation for registering block patterns and block pattern categories.

This expands the @param tag for the property argument available for the register() method in WP_Block_Patterns_Registry and WP_Block_Pattern_Cattegories_Registry.

See #53399.

#70 @SergeyBiryukov
2 years ago

In 52227:

Docs: Update documentation for the $plugin_data parameter of various hooks:

  • Document the structure of the $plugin_data array passed to the plugin_row_meta filter.
  • Document some missing values returned by get_plugin_data():
    • PluginURI
    • AuthorName
  • Link to get_plugin_data() and the plugin_row_meta filter as the canonical sources in other various filters and actions which receive the $plugin_data parameter:
    • network_admin_plugin_action_links
    • network_admin_plugin_action_links_{$plugin_file}
    • plugin_action_links
    • plugin_action_links_{$plugin_file}
    • plugin_auto_update_setting_html
    • manage_plugins_custom_column
    • after_plugin_row
    • after_plugin_row_{$plugin_file}
    • in_plugin_update_message-{$file}
  • Update documentation for the $response parameter of the in_plugin_update_message-{$file} filter:
    • Correct type for the id value. It contains a string like w.org/plugins/[plugin-name], not a numeric ID.
    • Update $icons, $banners, and $banners_rtl values to use typed array notation.

Follow-up to [8367], [8402], [12976], [16758], [26540], [30544], [34818], [51733], [52212], [52224].

See #53399.

#71 @johnbillion
2 years ago

In 52236:

Docs: Various docblock corrections and improvements.

See #53399

#73 @audrasjb
2 years ago

In 52239:

Docs: Document the globals used in some Privacy API methods.

See #53399.

#75 @SergeyBiryukov
2 years ago

In 52242:

Docs: Miscellaneous DocBlock corrections.

See #53399.

#77 @audrasjb
2 years ago

In 52249:

Docs: Miscellaneous DocBlock corrections in wp-admin/includes/post.php.

See #53399.

#78 @SergeyBiryukov
2 years ago

In 52251:

Docs: Improve consistency of some DocBlocks in wp-admin/includes/post.php.

Follow-up to [52249].

See #53399.

#79 @SergeyBiryukov
2 years ago

In 52297:

Docs: Use a duplicate hook reference for theme_file_path in WP_Theme::get_file_path().

Follow-up to [38578], [52279].

See #51506, #53399.

#81 @audrasjb
2 years ago

In 52298:

Docs: Docblock corrections in _disable_block_editor_for_navigation_post_type().

Follow-up to [52145].

See #53399.

#83 @johnbillion
2 years ago

In 52299:

Docs: Various docblock corrections.

See #53399

#85 @audrasjb
2 years ago

In 52301:

Docs: Misc Docblock corrections in duotone.php file.

Follow-up to [50929].

See #53399.

#88 @audrasjb
2 years ago

In 52302:

Docs: Miscellaneous Docblock corrections in several /block-supports files.

See #53399.

#91 @audrasjb
2 years ago

In 52303:

Docs: Add missing @param to wp_set_unique_slug_on_create_template_part().

Follow-up to [52062].

See #53399.

#93 @SergeyBiryukov
2 years ago

In 52305:

Docs: Fix typo in some get_edit_term_link() test DocBlocks.

Follow-up to [52180], [52255].

See #50225, #53399.

#96 @audrasjb
2 years ago

In 52306:

Docs: Add missing @since tag to WP_Theme_JSON_Schema functions.

Follow-up to [52049].

See #53399, #54336.

#97 @audrasjb
2 years ago

In 52307:

Docs: Docblock typo correction in WP_Theme_JSON_Schema.

Follow-up to [52306].

See #53399.

#100 @audrasjb
2 years ago

In 52317:

Docs: Miscellaneous Docblock corrections for block-template-utils.php file.

Follow-up to [52275], [52062].

See #53399.

#102 @audrasjb
2 years ago

In 52318:

Docs: Replace @since 5.9 with @since 5.9.0 in block-template-utils.php.

Follow-up to [52317], [52275], [52062].

See #53399.

#105 @SergeyBiryukov
2 years ago

In 52320:

Docs: Some documentation improvements for WP_Theme_JSON and WP_Theme_JSON_Resolver classes:

  • Make the @since 5.9.0 notes more specific. When mentioning that parameters or values have been added or changed, it is generally also helpful to include their exact names and the nature of changes for future reference.
  • Update some DocBlocks per the documentation standards.

Follow-up to [52049], [52306].

See #53399, #54336.

#106 @SergeyBiryukov
2 years ago

In 52321:

Docs: Further update some @since notes in WP_Theme_JSON methods for clarity.

Follow-up to [52049], [52306], [52320].

See #53399, #54336.

#107 @SergeyBiryukov
2 years ago

In 52323:

Docs: Add missing summary for WP_Theme_JSON_Resolver::get_merged_data().

Follow-up to [50959].

See #53399.

#108 @johnbillion
2 years ago

In 52332:

Docs: Various inline documentation corrections and improvements.

See #53399

#109 @SergeyBiryukov
2 years ago

In 52348:

Coding Standards: Simplify or wrap some long conditions in wp-includes/theme.php for better readability.

Includes adjusting some DocBlocks per the documentation standards.

Follow-up to [35595], [41937], [52256].

See #53359, #53399.

#110 @SergeyBiryukov
2 years ago

In 52352:

Docs: Correct the format of some comments per the documentation standards.

Follow-up to [10357], [10939], [43309], [51003], [51266], [51653], [51738], [52110].

See #53399.

#111 @SergeyBiryukov
2 years ago

In 52355:

Docs: Update some @var tags per the documentation standards.

Follow-up to [27398], [29487], [41626], [51003].

See #53399.

#112 @SergeyBiryukov
2 years ago

In 52356:

Docs: Update a comment in wp-admin/load-styles.php per the documentation standards.

Follow-up to [52352].

See #53399.

#113 @SergeyBiryukov
2 years ago

In 52357:

Docs: Capitalize "ID", when referring to a post ID, term ID, etc. in a more consistent way.

Follow-up to [48104].

See #53399.

#115 @audrasjb
2 years ago

In 52360:

Docs: Document the global used in upgrade_590() function.

Follow-up to [51917].

See #53399.

#117 @audrasjb
2 years ago

In 52361:

Docs: Capitalize "ID", when referring to a sidebar ID in a more consistent way.

Follow-up to [52016].

See #53399.

#120 @SergeyBiryukov
2 years ago

In 52362:

Docs: Capitalize "ID", when referring to a widget ID or sidebar ID, in a more consistent way.

Follow-up to [48104], [52357], [52361].

See #53399.

#122 @audrasjb
2 years ago

In 52366:

Docs: Typo correction in TinyMCE related JS file.

Follow-up to [45066].

See #53399.

#124 @johnbillion
2 years ago

In 52373:

Database: Correct and improve documentation for properties and parameters in wpdb.

See #53399

#125 @audrasjb
2 years ago

In 52394:

Docs: Typo correction in wp_dropdown_languages() DocBlock.

Follow-up to [52058].

See #53399.

#126 @SergeyBiryukov
2 years ago

In 52403:

Docs: Improve the @since 5.9.0 note for WP_Theme_JSON::PRESETS_METADATA.

Follow-up to [52320], [52401].

See #53399.

#127 @audrasjb
2 years ago

In 52410:

Docs: Typo correction in wp_get_layout_style() introduced in 5.9.

Follow-up to [52069].

See #53399.

#128 @audrasjb
2 years ago

In 52416:

Docs: Typo correction in validate_file() comments.

See #53399.

#129 @johnbillion
2 years ago

In 52422:

Docs: Miscellaneous inline documentation improvements.

See #53399

#130 @johnbillion
2 years ago

In 52423:

Docs: Further corrections and improvements to the inline documentation for wpdb.

See #53399, #54610

#131 @hellofromTonya
2 years ago

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

With 5.9 RC1 tomorrow, closing this ticket.

If there are any more changes required between now and the final 5.9 release, this can be referenced and reopened if necessary with dev-reviewed.

#54729 is open for continuation during the 6.0 cycle.

#133 @peterwilsoncc
2 years ago

In 53034:

KSES: Document HTML allow list is in lowercase.

Expand documentation of the wp_kses_allowed_html hook to indicate that developers must add permitted HTML tags and attributes in lowercase for KSES to recognise they are permitted.

Props r-a-y, SergeyBiryukov, peterwilsoncc.
Fixes #55407.
See #53399.

#134 @SergeyBiryukov
12 months ago

#53615 was marked as a duplicate.

Note: See TracTickets for help on using tickets.