WordPress.org

Make WordPress Core

Opened 7 months ago

Closed 2 months ago

Last modified 8 weeks ago

#49572 closed task (blessed) (fixed)

Docblock improvements for 5.5

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

Description

Previously:

Attachments (4)

49572.diff (2.5 KB) - added by pbiron 4 months ago.
Add 'term_order' to the description of the $orderby parameter of WP_Term_Query::__construct()
49572-bulk-actions-screen-id.diff (1.0 KB) - added by pbiron 3 months ago.
Correct DocBlock of bulk-actions-{$this->screen->id} filter
49572.returning-from-filter.diff (13.8 KB) - added by SergeyBiryukov 3 months ago.
49572-privacy-docblocks.diff (1.4 KB) - added by pbiron 2 months ago.
Correct @see references in DocBlocks for wp_privacy_process_personal_data_export_page() and wp_privacy_process_personal_data_erasure_page().

Download all attachments as: .zip

Change History (108)

#1 @SergeyBiryukov
7 months ago

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.

#2 @johnbillion
6 months ago

In 47461:

Docs: Various docblock corrections and improvements.

See #49572

#3 @SergeyBiryukov
6 months ago

In 47498:

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

See #49572.

#4 @SergeyBiryukov
6 months ago

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.

#5 @SergeyBiryukov
6 months ago

In 47545:

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

See #49572.

#6 @SergeyBiryukov
6 months ago

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

#7 @marekdedic
5 months ago

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

#8 @SergeyBiryukov
5 months ago

In 47610:

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

Props denisco.
See #49572.

#9 @SergeyBiryukov
5 months ago

In 47611:

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

See #49572.

#10 @SergeyBiryukov
5 months ago

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.

#11 @johnbillion
5 months ago

In 47754:

Docs: Misc docblock corrections and improvements.

See #49572

#12 @SergeyBiryukov
4 months ago

In 47782:

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

See #49572.

#13 @SergeyBiryukov
4 months ago

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.

#14 @TimothyBlynJacobs
4 months ago

In 47811:

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

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

#15 @SergeyBiryukov
4 months ago

In 47864:

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

See #49572.

#16 @SergeyBiryukov
4 months ago

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

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

#17 @SergeyBiryukov
4 months ago

In 47892:

Docs: Miscellaneous DocBlock corrections.

See #49572.

#18 @SergeyBiryukov
4 months ago

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.

#19 @SergeyBiryukov
4 months ago

In 47898:

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

Props pbiron.
See #49572.

#20 @desrosj
4 months ago

In 47912:

Docs: Fix a typo in the Docker compose file.

See #49572.

@pbiron
3 months ago

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

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


3 months ago

#23 @SergeyBiryukov
3 months ago

In 48067:

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

See #49572.

#24 @SergeyBiryukov
3 months ago

In 48068:

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

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

See #49572.

#25 @SergeyBiryukov
3 months ago

In 48085:

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

Follow-up to [48084].

See #49521, #49572.

#26 @desrosj
3 months ago

In 48091:

Docs: Add missing return type for _remove_theme_support().

See #49572.

#27 @johnbillion
3 months ago

In 48097:

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

See #50052, #49572

#28 @johnbillion
3 months ago

In 48098:

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

See #50117, #49572

#29 @johnbillion
3 months ago

In 48099:

Docs: Misc improvements to inline docs.

See #49572.

#30 @johnbillion
3 months ago

In 48100:

Docs: Remove unnecessary variables names from @return tags.

See #49572.

#31 @johnbillion
3 months ago

In 48101:

Docs: Fix some documentation errors in bundled themes.

See #49572.

#32 @SergeyBiryukov
3 months ago

In 48102:

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

See #49572.

#33 @SergeyBiryukov
3 months ago

In 48103:

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

See #49572.

#34 @SergeyBiryukov
3 months ago

In 48104:

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

See #49572.

#35 @SergeyBiryukov
3 months ago

In 48105:

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

See #49572.

#36 @SergeyBiryukov
3 months ago

In 48106:

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

See #49572.

#37 @SergeyBiryukov
3 months ago

In 48107:

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

See #49572.

#38 @SergeyBiryukov
3 months ago

In 48108:

Docs: Correct DocBlock placement for allow_subdirectory_install filter.

See #49572.

#39 @SergeyBiryukov
3 months ago

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.

#40 @SergeyBiryukov
3 months ago

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.

#41 @SergeyBiryukov
3 months ago

In 48139:

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

Follow-up to [48132].

See #49464, #49572.

#42 @SergeyBiryukov
3 months ago

In 48162:

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

See #49572.

#43 @SergeyBiryukov
3 months ago

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.

#44 @SergeyBiryukov
3 months ago

In 48164:

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

See #49572.

#45 @desrosj
3 months ago

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.

#46 @SergeyBiryukov
3 months ago

In 48175:

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

See #49572.

#48 @johnbillion
3 months ago

In 48183:

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

See #49572, #50052.

#49 @johnbillion
3 months ago

In 48184:

Docs: Miscellaneous docblock improvements.

See #49572.

#50 @SergeyBiryukov
3 months ago

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.

#51 @SergeyBiryukov
3 months ago

In 48189:

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

See #49572.

#52 @SergeyBiryukov
3 months ago

In 48190:

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

See #49572.

#53 @johnbillion
3 months ago

In 48192:

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

See #49572.

#54 @SergeyBiryukov
3 months ago

In 48193:

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

See #49572.

#55 @SergeyBiryukov
3 months ago

In 48197:

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

See #49572.

#56 @SergeyBiryukov
3 months ago

In 48198:

Docs: Miscellaneous DocBlock corrections.

See #49572.

#57 @SergeyBiryukov
3 months ago

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.

#58 @SergeyBiryukov
3 months ago

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.

#59 @SergeyBiryukov
3 months ago

In 48214:

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

Props stevenlinx.
Fixes #50502. See #49572.

#60 @SergeyBiryukov
3 months ago

In 48219:

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

Follow-up to [48197].

See #49572.

#61 @SergeyBiryukov
3 months ago

In 48220:

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

See #49572.

#62 @SergeyBiryukov
3 months ago

In 48221:

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

See #49572.

#63 @SergeyBiryukov
3 months ago

In 48226:

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

See #49927, #49572.

#64 @SergeyBiryukov
3 months ago

In 48264:

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

See #49572.

#65 @SergeyBiryukov
3 months ago

In 48275:

Docs: Spell "falsey" in a consistent way.

See #49572.

#66 @SergeyBiryukov
3 months ago

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.

#67 @SergeyBiryukov
3 months ago

In 48302:

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

Follow-up to [45232].

See #49572.

#68 @afercia
3 months ago

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.

#69 @SergeyBiryukov
3 months ago

In 48325:

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

Props hareesh-pillai.
See #49572.

#70 @desrosj
3 months ago

In 48344:

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

See #49572.

#71 @SergeyBiryukov
3 months ago

In 48364:

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

See #49572.

#72 @SergeyBiryukov
3 months ago

In 48365:

Docs: Miscellaneous DocBlock corrections.

See #49572.

#73 @johnbillion
3 months ago

In 48377:

Docs: Correct some @since entries added in 5.5.

See #49572

#74 @SergeyBiryukov
3 months ago

In 48408:

Docs: Miscellaneous DocBlock corrections.

See #49572.

#75 @SergeyBiryukov
2 months ago

In 48411:

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

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

See #49572, #43941, #45464.

#76 @SergeyBiryukov
2 months ago

In 48421:

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

Correct comments per the documentation standards.

See #49542, #49572.

#77 @SergeyBiryukov
2 months ago

In 48441:

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

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

See #49572.

#78 @SergeyBiryukov
2 months ago

In 48442:

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

See #49572.

#79 @SergeyBiryukov
2 months ago

In 48444:

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

See #49572.

#80 @SergeyBiryukov
2 months ago

In 48446:

Docs: Miscellaneous DocBlock corrections for plugin and theme updates.

See #49572.

#81 @johnbillion
2 months ago

In 48462:

Docs: Miscellaneous docblock corrections and improvements.

See #49572

#82 @johnbillion
2 months ago

In 48473:

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

See #49572

#83 @johnbillion
2 months ago

In 48475:

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

See #49572

@pbiron
2 months ago

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

#85 @johnbillion
2 months ago

In 48508:

Docs: Miscellaneous docblock corrections.

See #49572

#86 @SergeyBiryukov
2 months ago

In 48562:

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

See #44305, #49572.

#87 @johnbillion
2 months ago

In 48573:

Docs: Various corrections to inline docblocks.

See #49572

#88 @johnbillion
2 months ago

In 48574:

Docs: Various formatting improvements to inline docblocks.

See #49572

#89 @johnbillion
2 months ago

In 48576:

Docs: Further corrections and improvements to various inline docblocks.

See #49572

#90 @johnbillion
2 months ago

In 48585:

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

See #49572

#91 @johnbillion
2 months ago

In 48586:

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

See #49572, #50744

#92 @johnbillion
2 months ago

In 48590:

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

See #49572, #50744

#93 @SergeyBiryukov
2 months ago

In 48591:

Docs: Miscellaneous DocBlock corrections.

See #49572.

#94 @SergeyBiryukov
2 months ago

In 48599:

Docs: Correct some documentation for wp_update_term().

See #49572.

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


2 months ago

#96 @SergeyBiryukov
2 months ago

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.

#97 @SergeyBiryukov
2 months ago

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.

#98 @SergeyBiryukov
2 months ago

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.

#99 @SergeyBiryukov
2 months ago

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.

#100 @SergeyBiryukov
2 months ago

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

Follow-up: #50768

#101 @SergeyBiryukov
2 months ago

In 48624:

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

See #49572.

#102 @SergeyBiryukov
8 weeks ago

In 48634:

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

See #49572.

#103 @SergeyBiryukov
8 weeks ago

In 48635:

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

Follow-up to [48634].

See #49572.

#104 @johnbillion
8 weeks ago

In 48695:

Docs: Various fixes and improvements to inline documentation.

See #49572

Note: See TracTickets for help on using tickets.