Docblock improvements for 5.5

[SergeyBiryukov]

Previously:

• #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 47428:

Docs: Reorder @throws tags in WP_Customize_Nav_Menu_Setting and WP_Customize_Nav_Menu_Item_Setting for consistency with WP_Customize_Custom_CSS_Setting.

See #49572.

[johnbillion]

In 47461:

Docs: Various docblock corrections and improvements.

See #49572

[SergeyBiryukov]

In 47498:

Docs: Update inline comment in Tests_DB::test_locale_floats().

See #49572.

[SergeyBiryukov]

Related: [47170], [47502].

As noted in comment:103:ticket:48303, the $value parameter of WP_Dependencies::add_data() has a mixed type, but is 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().

Would be great to clean up this inconsistency one way or another.

[SergeyBiryukov]

In 47545:

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

See #49572.

[SergeyBiryukov]

Related: [47394]

Per comment:97:ticket:48303, image_downsize filter description could use a clarification about when the value can be an array (if another filter is filtering the value and returning an array intended as the short-circuited return value).

[marekdedic]

WP_Customize_Partial::$settings can be string[] instead of just array.

WP_Customize_Partial::__construct() parameter $args should be something like

@param array $args {
    @type string   $type
    @type string   $selector
    @type string[] $settings
    @type string   $primary_setting
    @type string   $capability
    @type callable $render_callback
    @type bool     $container_inclusive
    @type bool     $fallback_refresh
}

WP_Customize_Selective_Refresh::add_partial() argument $args should just reference WP_Customize_Partial::__construct() instead of being explicit.

Thanks,
Marek

[SergeyBiryukov]

In 47610:

Docs: Document the default value of $single and $prev_value parameters in various metadata functions.

Props denisco.
See #49572.

[SergeyBiryukov]

In 47611:

Docs: Synchronize parameter documentation for various metadata functions, update per the documentation standards.

See #49572.

[SergeyBiryukov]

In 47749:

Docs: Further update inline documentation for the wpdb class per the documentation standards.

Restore some previous edits from [46696], [47060], [47122], [47230] that were accidentally reverted in [47740].

See #49572.

[johnbillion]

In 47754:

Docs: Misc docblock corrections and improvements.

See #49572

[SergeyBiryukov]

In 47782:

Docs: Use 3-digit, x.x.x style semantic versioning for inline comments in populate_options().

See #49572.

[SergeyBiryukov]

In 47786:

Docs: Improve documentation for functions in wp-admin/install-helper.php per the documentation standards.

Synchronize descriptions with the functions' counterparts from wp-admin/includes/upgrade.php.

See #49572.

[TimothyBlynJacobs]

In 47811:

REST API: Add @since entries for rest_validate_value_from_schema().

See #49572, #48818, #44949, #50053, #48820, #49720, #42961, #44975, #43392, #38583.

[SergeyBiryukov]

In 47864:

Docs: Improve documentation for functions in wp-includes/category.php per the documentation standards.

See #49572.

[SergeyBiryukov]

In 47874:

Docs: Correct and clarify an inline comment about the upload_url_path and upload_path options in wp-admin/options-media.php.

Synchronize it with a similar comment in wp-admin/options.php.

See #49572.

[pbiron]

Add 'term_order' to the description of the $orderby parameter of WP_Term_Query::__construct()

[SergeyBiryukov]

In 47892:

Docs: Miscellaneous DocBlock corrections.

See #49572.

[SergeyBiryukov]

In 47897:

Docs: Reformat the orderby section of WP_Term_Query::__construct() for better readability.

This makes it more consistent with the fields section.

See #49572.

[SergeyBiryukov]

In 47898:

Docs: Document the term_order value for the orderby parameter of WP_Term_Query::__construct().

Props pbiron.
See #49572.

[desrosj]

In 47912:

Docs: Fix a typo in the Docker compose file.

See #49572.

[pbiron]

Correct DocBlock of bulk-actions-{$this->screen->id} filter

[pbiron]

props to @joyously for pointing out the need for 49572-bulk-actions-screen-id.diff.

​https://wordpress.slack.com/archives/C02RP4WU5/p1592256736420400

[SergeyBiryukov]

In 48067:

Docs: Consistently include an empty line between @since tag and @see, @link, or @global, per the documentation standards.

See #49572.

[SergeyBiryukov]

In 48068:

Docs: List the expected return type first for size_format() and wp_get_original_referer().

Follow-up to [46696], [47060].

See #49572.

[SergeyBiryukov]

In 48085:

Docs: Add missing $user_data parameter name to lostpassword_post and lostpassword_errors filter DocBlocks.

Follow-up to [48084].

See #49521, #49572.

[desrosj]

In 48091:

Docs: Add missing return type for _remove_theme_support().

See #49572.

[johnbillion]

In 48097:

Docs: Corrections and improvements to inline docs related to plugin and theme auto-updates.

See #50052, #49572

[johnbillion]

In 48098:

Docs: Corrections and improvements to inline docs related to XML sitemaps.

See #50117, #49572

[johnbillion]

In 48099:

Docs: Misc improvements to inline docs.

See #49572.

[johnbillion]

In 48100:

Docs: Remove unnecessary variables names from @return tags.

See #49572.

[johnbillion]

In 48101:

Docs: Fix some documentation errors in bundled themes.

See #49572.

[SergeyBiryukov]

In 48102:

Docs: Remove an empty line between @param and @return tags, per the documentation standards.

See #49572.

[SergeyBiryukov]

In 48103:

Docs: Synchronize and correct the documentation for wp_nav_menu() arguments in bundled themes.

See #49572.

[SergeyBiryukov]

In 48104:

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

See #49572.

[SergeyBiryukov]

In 48105:

Docs: Miscellaneous DocBlock corrections for plugin and theme installation and updates.

See #49572.

[SergeyBiryukov]

In 48106:

Docs: Use a hyphen with the "non" prefix in a more consistent way.

See #49572.

[SergeyBiryukov]

In 48107:

Docs: Miscellaneous DocBlock corrections for email filters in wp-includes/user.php.

See #49572.

[SergeyBiryukov]

In 48108:

Docs: Correct DocBlock placement for allow_subdirectory_install filter.

See #49572.

[SergeyBiryukov]

In 48110:

Docs: Remove extra spaces from @param tags.

Per the documentation standards, @param tags should be aligned with each other, but not with the @return tag.

See #49572.

[SergeyBiryukov]

In 48137:

Docs: Synchronize descriptions for some theme functions:

• get_stylesheet_directory()
• get_stylesheet_directory_uri()
• get_template_directory()
• get_template_directory_uri()

See #49572.

[SergeyBiryukov]

In 48139:

Docs: Use sentence case for comments in tests/kses.php, per the documentation standards.

Follow-up to [48132].

See #49464, #49572.

[SergeyBiryukov]

In 48162:

Docs: Improve DocBlocks in wp-admin/includes/class-wp-list-table.php per the documentation standards.

See #49572.

[SergeyBiryukov]

In 48163:

Docs: Synchronize documentation and variable names in wp_get_(plugin|theme)_file_editable_extensions() for consistency.

Add missing @since tag to wp_get_theme_file_editable_extensions().

See #49572.

[SergeyBiryukov]

In 48164:

Docs: Improve DocBlocks in wp-admin/includes/file.php per the documentation standards.

See #49572.

[desrosj]

In 48169:

Docs: Remove the custom-header-uploads feature from docs.

This was deprecated in [20212] in favor of passing ”uploads” => true to the custom-header feature, so it should not be specified as an available feature in the parameter documentation.

See #49572.

[SergeyBiryukov]

In 48175:

Docs: Spell "line breaks" in a consistent way.

See #49572.

[SergeyBiryukov]

See comment:58:ticket:16557 for some context on 49572.returning-from-filter.diff​.

[johnbillion]

In 48183:

Docs: Clarify the description of functions that check for and perform updates.

See #49572, #50052.

[johnbillion]

In 48184:

Docs: Miscellaneous docblock improvements.

See #49572.

[SergeyBiryukov]

In 48185:

Docs: Standardize on "Returning a value from the filter" vs. "Passing a value to the filter".

The filter is the callback function added with add_filter(), therefore the hook passes a value to the filter, and the filter returns a value to change its behaviour.

The documentation is referring to the latter.

Props johnbillion.
See #49572, #16557.

[SergeyBiryukov]

In 48189:

Docs: Improve DocBlocks in wp-includes/theme.php per the documentation standards.

See #49572.

[SergeyBiryukov]

In 48190:

Docs: Remove extra spaces from @ticket tag in unit tests.

See #49572.

[johnbillion]

In 48192:

Docs: Improvements to the inline docs for metadata related functions.

See #49572.

[SergeyBiryukov]

In 48193:

Docs: Synchronize some documentation for functions in wp-includes/option.php.

See #49572.

[SergeyBiryukov]

In 48197:

Docs: Improve documentation for optional parameters per the documentation standards.

See #49572.

[SergeyBiryukov]

In 48198:

Docs: Miscellaneous DocBlock corrections.

See #49572.

[SergeyBiryukov]

In 48200:

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

Follow-up to [48104]

See #49572.

[SergeyBiryukov]

In 48207:

Docs: Correct description for the $avoid_die parameter of wp_check_comment_flood().

The function always return a boolean value, never a WP_Error object.

See #49572, #39732.

[SergeyBiryukov]

In 48214:

Docs: Improve documentation for the $prev_value parameter and return result of various metadata update functions.

Props stevenlinx.
Fixes #50502. See #49572.

[SergeyBiryukov]

In 48219:

Docs: Correct documentation for the filter parameter of get_category() and get_tag().

Follow-up to [48197].

See #49572.

[SergeyBiryukov]

In 48220:

Docs: Improve documentation for Ajax comment tests per the documentation standards.

See #49572.

[SergeyBiryukov]

In 48221:

Docs: Remove @return void from some tests, per the documentation standards.

See #49572.

[SergeyBiryukov]

In 48226:

Docs: Correct $wp_query global reference in render_block().

See #49927, #49572.

[SergeyBiryukov]

In 48264:

Docs: Bundled Themes: Correct DocBlock placement for custom header and background argument filters.

See #49572.

[SergeyBiryukov]

In 48275:

Docs: Spell "falsey" in a consistent way.

See #49572.

[SergeyBiryukov]

In 48298:

Docs: Replace @returns tag in wp-admin/js/post.js with @return.

Per the documentation standards, @returns is an unsupported synonym, @return should be used instead.

Follow-up to [46800], [48232].

See #49572.

[SergeyBiryukov]

In 48302:

Docs: Correct spelling of "backward compatibility" per the Core Contributor Handbook glossary.

Follow-up to [45232].

See #49572.

[afercia]

In 48309:

Docs: Replace @returns tag in media/views/attachment/details.js with @return.

Per the documentation standards, @returns is an unsupported synonym, @return should be used instead.

Follow-up to [46800], [48232].
See #49572.

[SergeyBiryukov]

In 48325:

Docs: Fix typos in comments in tests/dependencies/jquery.php.

Props hareesh-pillai.
See #49572.

[desrosj]

In 48344:

Docs: Correct instances of “auto update” with “auto-update” for consistency.

See #49572.

[SergeyBiryukov]

In 48364:

Docs: Improve DocBlocks in wp-includes/nav-menu-template.php per the documentation standards.

See #49572.

[SergeyBiryukov]

In 48365:

Docs: Miscellaneous DocBlock corrections.

See #49572.

[johnbillion]

In 48377:

Docs: Correct some @since entries added in 5.5.

See #49572

[SergeyBiryukov]

In 48408:

Docs: Miscellaneous DocBlock corrections.

See #49572.

[SergeyBiryukov]

In 48411:

Docs: Synchronize and correct documentation for various metadata functions and filters.

Follow-up to [47390], [47611], [48192], [48402].

See #49572, #43941, #45464.

[SergeyBiryukov]

In 48421:

Coding Standards: Use strict comparison in WP_List_Util::filter().

Correct comments per the documentation standards.

See #49542, #49572.

[SergeyBiryukov]

In 48441:

Docs: Synchronize @since notes for add_magic_quotes() and wp_slash().

Follow-up to [48205], [48433].

See #49572.

[SergeyBiryukov]

In 48442:

Docs: Correct comments in tests/formatting/WPSlash.php per the documentation standards.

See #49572.

[SergeyBiryukov]

In 48444:

Docs: Improve documentation for sanitize_user(), sanitize_title(), sanitize_title_with_dashes().

See #49572.

[SergeyBiryukov]

In 48446:

Docs: Miscellaneous DocBlock corrections for plugin and theme updates.

See #49572.

[johnbillion]

In 48462:

Docs: Miscellaneous docblock corrections and improvements.

See #49572

[johnbillion]

In 48473:

Docs: Correct and improve inline docs for parameters that accept a callback function.

See #49572

[johnbillion]

In 48475:

Docs: Improve docs for arguments that accept a numerically indexed array of associative arrays.

See #49572

[pbiron]

Correct @see references in DocBlocks for wp_privacy_process_personal_data_export_page() and wp_privacy_process_personal_data_erasure_page().

[pbiron]

re: 49572-privacy-docblocks.diff​, see ​https://meta.trac.wordpress.org/ticket/5318

[johnbillion]

In 48508:

Docs: Miscellaneous docblock corrections.

See #49572

[SergeyBiryukov]

In 48562:

Docs: Improve formatting of the $fields parameter description in WP_Term_Query::__construct().

See #44305, #49572.

[johnbillion]

In 48573:

Docs: Various corrections to inline docblocks.

See #49572

[johnbillion]

In 48574:

Docs: Various formatting improvements to inline docblocks.

See #49572

[johnbillion]

In 48576:

Docs: Further corrections and improvements to various inline docblocks.

See #49572

[johnbillion]

In 48585:

Docs: Use more appropriate variable names in the inline docs for action and filter parameters.

See #49572

[johnbillion]

In 48586:

Docs: First pass at some inline docs fixes mostly made by PHPCBF.

See #49572, #50744

[johnbillion]

In 48590:

Docs: Another pass at some inline docs fixes mostly made by PHPCBF.

See #49572, #50744

[SergeyBiryukov]

In 48591:

Docs: Miscellaneous DocBlock corrections.

See #49572.

[SergeyBiryukov]

In 48599:

Docs: Correct some documentation for wp_update_term().

See #49572.

[SergeyBiryukov]

In 48614:

Docs: Remove outdated statement in bulk_actions-{$this->screen->id} filter description.

As of WordPress 4.7, developers can register their own bulk actions on list table screens.

Follow-up to [17297], [38647].

Props joyously, pbiron.
See #49572.

[SergeyBiryukov]

In 48615:

Docs: Correct @since tags for some WP_List_Table hooks:

• views_{$this->screen->id}
• bulk_actions-{$this->screen->id}
• manage_{$this->screen->id}_sortable_columns

Follow-up to [15491], [15578], [26401].

See #49572.

[SergeyBiryukov]

In 48616:

Docs: Correct @see references for privacy hooks:

• wp_privacy_personal_data_export_page
• wp_privacy_personal_data_erasure_page

Hooks should be single-quoted when referenced.

Props pbiron, coffee2code.
See #49572, ​#meta5318.

[SergeyBiryukov]

In 48617:

Docs: Add a reference to WP_Customize_Partial::__construct() for information on accepted arguments in WP_Customize_Selective_Refresh::add_partial().

Synchronize the documentation between two places, use WP_Customize_Partial::__construct() as the canonical source.

Props marekdedic.
See #49572.

[SergeyBiryukov]

Follow-up: #50768

[SergeyBiryukov]

In 48624:

Docs: Synchronize some comments in wp-admin/revision.php.

See #49572.

[SergeyBiryukov]

In 48634:

Docs: Synchronize documentation for get_lastpostdate() and get_lastpostmodified().

See #49572.

[SergeyBiryukov]

In 48635:

Posts, Post Types: Pass correct variable to the get_lastpostdate filter.

Follow-up to [48634].

See #49572.

[johnbillion]

In 48695:

Docs: Various fixes and improvements to inline documentation.

See #49572