WordPress.org

Make WordPress Core

Opened 4 months ago

Last modified 7 hours ago

#49572 new task (blessed)

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 (3)

49572.diff (2.5 KB) - added by pbiron 5 weeks 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 weeks ago.
Correct DocBlock of bulk-actions-{$this->screen->id} filter
49572.returning-from-filter.diff (13.8 KB) - added by SergeyBiryukov 9 days ago.

Download all attachments as: .zip

Change History (71)

#1 @SergeyBiryukov
4 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
4 months ago

In 47461:

Docs: Various docblock corrections and improvements.

See #49572

#3 @SergeyBiryukov
3 months ago

In 47498:

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

See #49572.

#4 @SergeyBiryukov
3 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
3 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
3 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
3 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
2 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
2 months ago

In 47611:

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

See #49572.

#10 @SergeyBiryukov
2 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
2 months ago

In 47754:

Docs: Misc docblock corrections and improvements.

See #49572

#12 @SergeyBiryukov
8 weeks ago

In 47782:

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

See #49572.

#13 @SergeyBiryukov
8 weeks 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
7 weeks 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
5 weeks ago

In 47864:

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

See #49572.

#16 @SergeyBiryukov
5 weeks 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
5 weeks ago

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

#17 @SergeyBiryukov
5 weeks ago

In 47892:

Docs: Miscellaneous DocBlock corrections.

See #49572.

#18 @SergeyBiryukov
5 weeks 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
5 weeks 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 weeks ago

In 47912:

Docs: Fix a typo in the Docker compose file.

See #49572.

@pbiron
3 weeks ago

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

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


3 weeks ago

#23 @SergeyBiryukov
3 weeks 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 weeks 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
2 weeks 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
2 weeks ago

In 48091:

Docs: Add missing return type for _remove_theme_support().

See #49572.

#27 @johnbillion
2 weeks ago

In 48097:

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

See #50052, #49572

#28 @johnbillion
2 weeks ago

In 48098:

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

See #50117, #49572

#29 @johnbillion
2 weeks ago

In 48099:

Docs: Misc improvements to inline docs.

See #49572.

#30 @johnbillion
2 weeks ago

In 48100:

Docs: Remove unnecessary variables names from @return tags.

See #49572.

#31 @johnbillion
2 weeks ago

In 48101:

Docs: Fix some documentation errors in bundled themes.

See #49572.

#32 @SergeyBiryukov
2 weeks ago

In 48102:

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

See #49572.

#33 @SergeyBiryukov
2 weeks ago

In 48103:

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

See #49572.

#34 @SergeyBiryukov
2 weeks ago

In 48104:

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

See #49572.

#35 @SergeyBiryukov
2 weeks ago

In 48105:

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

See #49572.

#36 @SergeyBiryukov
2 weeks ago

In 48106:

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

See #49572.

#37 @SergeyBiryukov
2 weeks ago

In 48107:

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

See #49572.

#38 @SergeyBiryukov
2 weeks ago

In 48108:

Docs: Correct DocBlock placement for allow_subdirectory_install filter.

See #49572.

#39 @SergeyBiryukov
2 weeks 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
12 days 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
12 days 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
10 days ago

In 48162:

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

See #49572.

#43 @SergeyBiryukov
10 days 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
10 days ago

In 48164:

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

See #49572.

#45 @desrosj
10 days 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
9 days ago

In 48175:

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

See #49572.

#48 @johnbillion
9 days ago

In 48183:

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

See #49572, #50052.

#49 @johnbillion
9 days ago

In 48184:

Docs: Miscellaneous docblock improvements.

See #49572.

#50 @SergeyBiryukov
9 days 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
8 days ago

In 48189:

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

See #49572.

#52 @SergeyBiryukov
8 days ago

In 48190:

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

See #49572.

#53 @johnbillion
8 days ago

In 48192:

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

See #49572.

#54 @SergeyBiryukov
8 days ago

In 48193:

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

See #49572.

#55 @SergeyBiryukov
7 days ago

In 48197:

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

See #49572.

#56 @SergeyBiryukov
7 days ago

In 48198:

Docs: Miscellaneous DocBlock corrections.

See #49572.

#57 @SergeyBiryukov
7 days 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
7 days 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
6 days 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
6 days ago

In 48219:

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

Follow-up to [48197].

See #49572.

#61 @SergeyBiryukov
6 days ago

In 48220:

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

See #49572.

#62 @SergeyBiryukov
6 days ago

In 48221:

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

See #49572.

#63 @SergeyBiryukov
5 days ago

In 48226:

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

See #49927, #49572.

#64 @SergeyBiryukov
4 days ago

In 48264:

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

See #49572.

#65 @SergeyBiryukov
3 days ago

In 48275:

Docs: Spell "falsey" in a consistent way.

See #49572.

#66 @SergeyBiryukov
20 hours 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
18 hours ago

In 48302:

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

Follow-up to [45232].

See #49572.

#68 @afercia
7 hours 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.

Note: See TracTickets for help on using tickets.