WordPress.org

Make WordPress Core

Opened 4 months ago

Closed 13 days ago

#51800 closed task (blessed) (fixed)

Docblock improvements for WP 5.7

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

Description

Previously:

Attachments (2)

51800.diff (1.5 KB) - added by johnbillion 2 months ago.
51800.link-template-null.patch (4.2 KB) - added by ocean90 4 weeks ago.

Download all attachments as: .zip

Change History (57)

#1 @johnbillion
4 months ago

In 49670:

Docs: Clarify and standardise on terminology used for rewrite rule endpoint masks.

See #51800

#2 @johnbillion
4 months ago

In 49671:

Docs: Add missing @since tags.

See #51800

#3 @johnbillion
4 months ago

In 49672:

Docs: Document parameters that accept an array of integers using typed array notation.

While many of these parameters also technically accept an array of numerical strings, they are all ultimately cast to an array of integers. Documenting them as such assists developers in understanding the expected types.

See #51800, #41756

#4 @SergeyBiryukov
4 months ago

In 49675:

Docs: Add missing @since tags for WP_Upgrader_Skin methods.

See #51800.

#5 @SergeyBiryukov
4 months ago

In 49678:

Docs: Correct @since tag for the class-wp-widget-area-customize-control.php file.

Per the documentation standards, the file header @since tag is supposed to specify when the file was introduced.

Follow-up to [35389].

See #51800.

#6 @SergeyBiryukov
3 months ago

In 49688:

Docs: Clarify that the $class argument of wp_list_bookmarks() can accept an array.

Follow-up to [32906].

See #51855, #51800.

#7 @johnbillion
3 months ago

In 49692:

Docs: Various docblock corrections relating to parameter types.

See #51800

#8 @johnbillion
3 months ago

In 49693:

Docs: Upgrade more parameters in docblocks to used typed array notation.

See #51800, #41756

#9 @SergeyBiryukov
3 months ago

In 49698:

Docs: Use typed array notation for the $size parameter of embed_defaults filter.

Previously committed in [42876], accidentally reverted in [44154].

See #51800.

#10 @johnbillion
3 months ago

In 49700:

Docs: Corrections and improvements to docs for properties of the WP_Query class.

This also adds additional type hinting inside some methods to help IDEs.

See #51800

#11 @SergeyBiryukov
3 months ago

In 49735:

Docs: Clarify the $format parameter description in comment_time().

See #51800.

#12 @peterwilsoncc
3 months ago

In 49758:

Docs, Tests: Correctly capitalize JavaScript.

Correct Javascript to JavaScript within Wordpress core ;)

See #51800, #51802.

#13 @SergeyBiryukov
3 months ago

In 49769:

Docs: Fix typo in references to WP_Error in some DocBlocks.

See #51800.

#14 @SergeyBiryukov
3 months ago

In 49785:

Docs: Fix typo in some DocBlocks.

See #51800.

#15 @johnbillion
3 months ago

In 49787:

Docs: Fix some docblock issues introduced in 5.6.

See #51800

#16 @johnbillion
3 months ago

In 49788:

Upgrade/Install: Remove a duplicate description for the upgrader_overwrote_package action.

See #51800, #9757

#17 @johnbillion
3 months ago

In 49789:

Docs: Various docblock corrections.

See #51800

#18 @johnbillion
3 months ago

In 49790:

Docs: Various docblock improvements.

See #51800

#19 @johnbillion
3 months ago

In 49802:

Docs: Correct the documentation for the map_meta_cap() function and its filter.

See #51800

#20 @SergeyBiryukov
3 months ago

In 49837:

Docs: Update the reference to Appearance → Theme Editor admin menu item in the inline documentation.

Follow-up to [42685].

See #51800.

#21 @SergeyBiryukov
3 months ago

In 49858:

Docs: Move sanitize_file_name filter documentation to the canonical place.

See #51800.

#22 @SergeyBiryukov
3 months ago

In 49859:

Docs: Move locale filter documentation to the canonical place.

See #51800.

#23 @johnbillion
2 months ago

In 49926:

Docs: Various docblock corrections particularly relating to boolean types.

See #51800

#24 @johnbillion
2 months ago

In 49927:

Docs: Promote many bool types to true or false where only that value is used.

See #51800

#25 @SergeyBiryukov
2 months ago

@johnbillion It looks like [49926] reverts string|string[] back to string|array for wp_unslash(), but not for wp_slash(), essentially reverting [47400], but keeping [48441]. Is that intentional?

#26 @SergeyBiryukov
2 months ago

In 49928:

Docs: Synchronize and correct documentation for has_filter() and WP_Hook::has_filter().

WP_Hook::has_filter() returns true if $function_to_check is omitted and the hook being checked has one or more registered callbacks.

Follow-up to [49927].

See #51800.

#27 @johnbillion
2 months ago

@SergeyBiryukov Thanks. This was an intentional change because the array returned by wp_unslash() is not always an array of strings, for example when unslashing an array of arrays. I'll do a follow-up.

@johnbillion
2 months ago

#28 @SergeyBiryukov
2 months ago

In 49929:

Docs: In various @return tags, list the expected type first, instead of false or WP_Error.

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

See #51800.

#29 follow-up: @johnbillion
2 months ago

@SergeyBiryukov Does 51800.diff look ok?

#30 in reply to: ↑ 29 @SergeyBiryukov
2 months ago

Replying to johnbillion:

Does 51800.diff look ok?

Yes, looks good to me :) Thanks!

#31 @SergeyBiryukov
2 months ago

In 49934:

Docs: Fix typo in wp_set_comment_status filter DocBlock.

Follow-up to [49926].

See #51800.

#32 @SergeyBiryukov
2 months ago

In 49935:

Docs: Use more consistent descriptions for void|false return values.

See #51800.

#33 @johnbillion
2 months ago

In 49936:

Docs: Corrections and improvements to types used in various docblocks.

See #51800, #52217

#34 @SergeyBiryukov
2 months ago

In 49941:

Docs: Correct description for wp_parse_list().

The function simply converts a comma- or space-separated list of scalar values to an array and does not perform any sanitization on its own.

Follow-up to [44546].

Props johnjamesjacoby.
See #51800.

#35 @johnbillion
2 months ago

In 49942:

Docs: Miscellaneous docblock corrections and improvements.

See #51800.

#36 @johnbillion
2 months ago

In 49946:

Plugins: Replace usage of $this in action and filter parameter docblocks with more appropriate variable names.

See #51800, #52217

Fixes #52243

#37 @johnbillion
2 months ago

In 49947:

Taxonomy: Correct and clarify documentation for the return types of term query functions.

See #51800, #38266

#38 @johnbillion
8 weeks ago

In 49955:

REST API: Corrections and improvements to docblocks for REST API filters.

See #51800

#39 @SergeyBiryukov
7 weeks ago

In 49963:

Docs: In various @return tags, list the expected type first, instead of false.

Follow-up to [46696], [47060], [49926], [49927], [49929].

See #51800.

#40 @SergeyBiryukov
7 weeks ago

In 49965:

Coding Standards: Fix WPCS issue in [49963].

Props pawki07, mukesh27.
Fixes #52316. See #51800.

#41 @SergeyBiryukov
7 weeks ago

In 49968:

Docs: Correct description for wp_slash() and wp_unslash().

The array received or returned by these functions is not always an array of strings, for example when slashing or unslashing an array of arrays.

Follow-up to [47400], [48441], [49926].

Props johnbillion.
See #51800.

#42 @SergeyBiryukov
7 weeks ago

In 49977:

Docs: Link to the parent function for accepted arguments in some filters for HTML output.

See #51800.

#43 @SergeyBiryukov
5 weeks ago

In 50122:

Docs: Add @since notes for some of the recently introduced meta capabilities.

Follow-up to [42832], [43085], [43147], [43155], [43381], [44973], [50114].

See #51800.

#44 @SergeyBiryukov
5 weeks ago

In 50138:

Docs: Add a @since note to map_meta_cap() for the update_https capability.

Follow-up to [50122], [50131].

See #51800.

#45 @SergeyBiryukov
5 weeks ago

In 50175:

Docs: Consistently document the default value for $args parameter in various cron functions.

See #51800.

#46 @SergeyBiryukov
4 weeks ago

In 50233:

Twenty Twenty-One: Capitalize translator comments consistently.

Follow-up to [45932].

See #51800.

#47 @SergeyBiryukov
4 weeks ago

In 50234:

I18N: Use the actual placeholder instead of a number in translator comments if the corresponding string does not use numbered placeholders.

Adjust some newly introduced strings to remove unnecessary numbered placeholders for consistency.

Follow-up to [42827].

See #51800.

#48 @peterwilsoncc
4 weeks ago

In 50257:

Posts/Post Types: Improve documentation of get_posts().

Add references to WP_Query to the documentation of get_posts(). As the developer documentation for WP_Query includes an expanded explanation a full link to developer.wordpress.org is included rather than a standard @see.

Props dam6pl, peterwilsoncc.
See #51852, #51800.

#49 @SergeyBiryukov
4 weeks ago

In 50264:

Docs: Update some recently added inline comments per the documentation standards.

Follow-up to [50256], [50258], [50259].

See #51800.

#50 @ocean90
3 weeks ago

In 50340:

Docs: Improve parameter types for various URL functions and filters that also accept null.

See #51800.

#51 @SergeyBiryukov
3 weeks ago

In 50372:

Docs: Correct the type of $widget_id argument in is_active_widget().

See #51800.

#52 @SergeyBiryukov
3 weeks ago

In 50373:

Docs: Correct the alternative hook name for the deprecated whitelist_options hook.

Follow-up to [48121].

See #51800.

#53 @johnbillion
2 weeks ago

In 50395:

Docs: Various docblock corrections and improvements.

See #51800

#54 @SergeyBiryukov
2 weeks ago

In 50407:

Docs: Document the usage of $pagenow global in a few functions.

See #51800.

#55 @SergeyBiryukov
13 days ago

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

Follow-up: #52628

Note: See TracTickets for help on using tickets.