Make WordPress Core

Opened 3 years ago

Closed 2 years ago

#51800 closed task (blessed) (fixed)

Docblock improvements for WP 5.7

Reported by: sergeybiryukov's profile 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 years ago.
51800.link-template-null.patch (4.2 KB) - added by ocean90 2 years ago.

Download all attachments as: .zip

Change History (57)

#1 @johnbillion
3 years ago

In 49670:

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

See #51800

#2 @johnbillion
3 years ago

In 49671:

Docs: Add missing @since tags.

See #51800

#3 @johnbillion
3 years 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
3 years ago

In 49675:

Docs: Add missing @since tags for WP_Upgrader_Skin methods.

See #51800.

#5 @SergeyBiryukov
3 years 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 years 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 years ago

In 49692:

Docs: Various docblock corrections relating to parameter types.

See #51800

#8 @johnbillion
3 years ago

In 49693:

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

See #51800, #41756

#9 @SergeyBiryukov
3 years 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 years 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
2 years ago

In 49735:

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

See #51800.

#12 @peterwilsoncc
2 years ago

In 49758:

Docs, Tests: Correctly capitalize JavaScript.

Correct Javascript to JavaScript within Wordpress core ;)

See #51800, #51802.

#13 @SergeyBiryukov
2 years ago

In 49769:

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

See #51800.

#14 @SergeyBiryukov
2 years ago

In 49785:

Docs: Fix typo in some DocBlocks.

See #51800.

#15 @johnbillion
2 years ago

In 49787:

Docs: Fix some docblock issues introduced in 5.6.

See #51800

#16 @johnbillion
2 years ago

In 49788:

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

See #51800, #9757

#17 @johnbillion
2 years ago

In 49789:

Docs: Various docblock corrections.

See #51800

#18 @johnbillion
2 years ago

In 49790:

Docs: Various docblock improvements.

See #51800

#19 @johnbillion
2 years ago

In 49802:

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

See #51800

#20 @SergeyBiryukov
2 years 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
2 years ago

In 49858:

Docs: Move sanitize_file_name filter documentation to the canonical place.

See #51800.

#22 @SergeyBiryukov
2 years ago

In 49859:

Docs: Move locale filter documentation to the canonical place.

See #51800.

#23 @johnbillion
2 years ago

In 49926:

Docs: Various docblock corrections particularly relating to boolean types.

See #51800

#24 @johnbillion
2 years ago

In 49927:

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

See #51800

#25 @SergeyBiryukov
2 years 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 years 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 years 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 years ago

#28 @SergeyBiryukov
2 years 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 years ago

@SergeyBiryukov Does 51800.diff look ok?

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

Replying to johnbillion:

Does 51800.diff look ok?

Yes, looks good to me :) Thanks!

#31 @SergeyBiryukov
2 years ago

In 49934:

Docs: Fix typo in wp_set_comment_status filter DocBlock.

Follow-up to [49926].

See #51800.

#32 @SergeyBiryukov
2 years ago

In 49935:

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

See #51800.

#33 @johnbillion
2 years ago

In 49936:

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

See #51800, #52217

#34 @SergeyBiryukov
2 years 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 years ago

In 49942:

Docs: Miscellaneous docblock corrections and improvements.

See #51800.

#36 @johnbillion
2 years 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 years ago

In 49947:

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

See #51800, #38266

#38 @johnbillion
2 years ago

In 49955:

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

See #51800

#39 @SergeyBiryukov
2 years 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
2 years ago

In 49965:

Coding Standards: Fix WPCS issue in [49963].

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

#41 @SergeyBiryukov
2 years 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
2 years ago

In 49977:

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

See #51800.

#43 @SergeyBiryukov
2 years 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
2 years 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
2 years ago

In 50175:

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

See #51800.

#46 @SergeyBiryukov
2 years ago

In 50233:

Twenty Twenty-One: Capitalize translator comments consistently.

Follow-up to [45932].

See #51800.

#47 @SergeyBiryukov
2 years 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
2 years 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
2 years ago

In 50264:

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

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

See #51800.

#50 @ocean90
2 years ago

In 50340:

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

See #51800.

#51 @SergeyBiryukov
2 years ago

In 50372:

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

See #51800.

#52 @SergeyBiryukov
2 years ago

In 50373:

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

Follow-up to [48121].

See #51800.

#53 @johnbillion
2 years ago

In 50395:

Docs: Various docblock corrections and improvements.

See #51800

#54 @SergeyBiryukov
2 years ago

In 50407:

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

See #51800.

#55 @SergeyBiryukov
2 years ago

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

Follow-up: #52628

Note: See TracTickets for help on using tickets.