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