Docblock improvements for WP 5.9

[desrosj]

Previously:

• #52628 (5.8)
• #51800 (5.7)
• #50768 (5.6)
• #49572 (5.5)
• #48303 (5.4)
• #47110 (5.3)
• #46543 (5.2)
• #42505 (5.1)
• #41017 (4.9)
• #39130 (4.8)
• #37770 (4.7)
• #32246 (4.6)

[SergeyBiryukov]

In 51278:

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

See #53399.

[johnbillion]

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

[johnbillion]

In 51298:

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

See #53399

[johnbillion]

In 51299:

Docs: Miscellaneous formatting corrections for docblocks.

See #53399

[johnbillion]

In 51300:

Docs: Descriptive improvements and corrections for various docblocks.

See #53399

[SergeyBiryukov]

Looks like [51300] accidentally reverted [51299].

[johnbillion]

In 51301:

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

See #53399

[johnbillion]

In 51302:

Docs: Further type corrections and improvements for various docblocks.

See #53399

[SergeyBiryukov]

In 51303:

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

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

See #53399.

[SergeyBiryukov]

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.

[johnbillion]

In 51330:

Docs: Miscellaneous docblock improvements.

See #53399

[SergeyBiryukov]

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.

[SergeyBiryukov]

In 51430:

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

See #53399.

[johnbillion]

In 51477:

Docs: Miscellaneous docblock corrections and improvements.

See #53399

[SergeyBiryukov]

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

[johnbillion]

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.

[SergeyBiryukov]

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.

[SergeyBiryukov]

In 51495:

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

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

See #53399.

[johnbillion]

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

[johnbillion]

In 51514:

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

See #53399

[SergeyBiryukov]

In 51527:

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

Follow-up to [30758].

See #53399.

[johnbillion]

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

[SergeyBiryukov]

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.

[SergeyBiryukov]

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.

[SergeyBiryukov]

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.

[SergeyBiryukov]

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.

[SergeyBiryukov]

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?

[SergeyBiryukov]

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.

[SergeyBiryukov]

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.

[SergeyBiryukov]

In 51730:

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

Follow-up to [46754].

See #53399.

[johnbillion]

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.

[SergeyBiryukov]

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.

[johnbillion]

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

[johnjamesjacoby]

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.

[SergeyBiryukov]

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.

[johnbillion]

In 51851:

Docs: Miscellaneous docblock corrections and improvements.

See #52217, #53399

[audrasjb]

Docs: Toolbar: Miscellaneous docblock corrections and improvements.

[audrasjb]

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

[johnbillion]

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

[johnbillion]

In 51886:

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

Props audrasjb

See #53399

[johnbillion]

In 51915:

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

See #53399

[peterwilsoncc]

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.

[SergeyBiryukov]

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.

[johnbillion]

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.

[johnbillion]

In 51950:

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

See #53399, #28992, #40653

[johnbillion]

In 51955:

Docs: Miscellaneous docblock improvements.

See #53399

[SergeyBiryukov]

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.

[johnbillion]

In 51957:

Docs: Miscellaneous docblock improvements.

See #53399

[johnbillion]

In 51958:

Application Passwords: Various docblock improvements.

See #53399, #42790

[SergeyBiryukov]

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.

[SergeyBiryukov]

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.

[johnbillion]

In 52034:

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

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

[johnbillion]

In 52035:

Docs: Various docblock improvements and corrections.

See #53399

[ocean90]

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.

[desrosj]

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.

[SergeyBiryukov]

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.

[johnbillion]

In 52127:

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

See #53399

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

[audrasjb]

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

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 .

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

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

[johnbillion]

In 52204:

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

See #53399

[johnbillion]

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

https://core.trac.wordpress.org/changeset/52205

https://core.trac.wordpress.org/changeset/52205

https://core.trac.wordpress.org/changeset/52204

[audrasjb]

In 52208:

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

Props andy-schmidt.
See #53399.

Committed in https://core.trac.wordpress.org/changeset/52208

[desrosj]

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.

[SergeyBiryukov]

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.

[johnbillion]

In 52236:

Docs: Various docblock corrections and improvements.

See #53399

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

[audrasjb]

In 52239:

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

See #53399.

Committed in https://core.trac.wordpress.org/changeset/52239

[SergeyBiryukov]

In 52242:

Docs: Miscellaneous DocBlock corrections.

See #53399.

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

[audrasjb]

In 52249:

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

See #53399.

[SergeyBiryukov]

In 52251:

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

Follow-up to [52249].

See #53399.

[SergeyBiryukov]

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.

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

[audrasjb]

In 52298:

Docs: Docblock corrections in _disable_block_editor_for_navigation_post_type().

Follow-up to [52145].

See #53399.

Committed in https://core.trac.wordpress.org/changeset/52298

[johnbillion]

In 52299:

Docs: Various docblock corrections.

See #53399

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

[audrasjb]

In 52301:

Docs: Misc Docblock corrections in duotone.php file.

Follow-up to [50929].

See #53399.

Committed in https://core.trac.wordpress.org/changeset/52301

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

[audrasjb]

In 52302:

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

See #53399.

Committed in https://core.trac.wordpress.org/changeset/52302

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

[audrasjb]

In 52303:

Docs: Add missing @param to wp_set_unique_slug_on_create_template_part().

Follow-up to [52062].

See #53399.

Committed in https://core.trac.wordpress.org/changeset/52303

[SergeyBiryukov]

In 52305:

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

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

See #50225, #53399.

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

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

[audrasjb]

In 52306:

Docs: Add missing @since tag to WP_Theme_JSON_Schema functions.

Follow-up to [52049].

See #53399, #54336.

[audrasjb]

In 52307:

Docs: Docblock typo correction in WP_Theme_JSON_Schema.

Follow-up to [52306].

See #53399.

Committed in https://core.trac.wordpress.org/changeset/52307

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

[audrasjb]

In 52317:

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

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

See #53399.

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

[audrasjb]

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.

Committed in https://core.trac.wordpress.org/changeset/52318

Committed in https://core.trac.wordpress.org/changeset/52317

[SergeyBiryukov]

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.

[SergeyBiryukov]

In 52321:

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

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

See #53399, #54336.

[SergeyBiryukov]

In 52323:

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

Follow-up to [50959].

See #53399.

[johnbillion]

In 52332:

Docs: Various inline documentation corrections and improvements.

See #53399

[SergeyBiryukov]

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.

[SergeyBiryukov]

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.

[SergeyBiryukov]

In 52355:

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

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

See #53399.

[SergeyBiryukov]

In 52356:

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

Follow-up to [52352].

See #53399.

[SergeyBiryukov]

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.

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

[audrasjb]

In 52360:

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

Follow-up to [51917].

See #53399.

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

[audrasjb]

In 52361:

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

Follow-up to [52016].

See #53399.

Committed in https://core.trac.wordpress.org/changeset/52360

Committed in https://core.trac.wordpress.org/changeset/52361

[SergeyBiryukov]

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.

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

[audrasjb]

In 52366:

Docs: Typo correction in TinyMCE related JS file.

Follow-up to [45066].

See #53399.

Committed in https://core.trac.wordpress.org/changeset/52366

[johnbillion]

In 52373:

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

See #53399

[audrasjb]

In 52394:

Docs: Typo correction in wp_dropdown_languages() DocBlock.

Follow-up to [52058].

See #53399.

[SergeyBiryukov]

In 52403:

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

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

See #53399.

[audrasjb]

In 52410:

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

Follow-up to [52069].

See #53399.

[audrasjb]

In 52416:

Docs: Typo correction in validate_file() comments.

See #53399.

[johnbillion]

In 52422:

Docs: Miscellaneous inline documentation improvements.

See #53399

[johnbillion]

In 52423:

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

See #53399, #54610

[hellofromTonya]

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.

Committed via https://core.trac.wordpress.org/changeset/52249.

[peterwilsoncc]

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.

[SergeyBiryukov]

#53615 was marked as a duplicate.