WordPress.org

Make WordPress Core

Opened 8 months ago

Closed 4 months ago

Last modified 4 months ago

#52628 closed task (blessed) (fixed)

Docblock improvements for WP 5.8

Reported by: SergeyBiryukov Owned by: SergeyBiryukov
Milestone: 5.8 Priority: normal
Severity: normal Version:
Component: General Keywords: has-patch commit dev-reviewed
Focuses: docs Cc:

Description (last modified by SergeyBiryukov)

Previously:

Attachments (2)

52628.htmlhint.diff (1.0 KB) - added by sabernhardt 7 months ago.
52628.class-walker-page.diff (691 bytes) - added by alexstine 6 months ago.

Download all attachments as: .zip

Change History (76)

#1 @SergeyBiryukov
8 months ago

  • Description modified (diff)

#2 @SergeyBiryukov
8 months ago

In 50434:

Docs: Correct function name in add_settings_field() DocBlock.

See #52628.

#3 @SergeyBiryukov
8 months ago

In 50460:

Docs: Clarify a comment about wp_opcache_invalidate() in _copy_dir().

Follow-up to [48160].

See #52628.

#4 @SergeyBiryukov
8 months ago

In 50484:

Docs: Update documentation in some WP_REST_Request tests per the documentation standards.

Follow-up to [49329].

See #52628.

#5 @SergeyBiryukov
8 months ago

In 50491:

Docs: Update inline comments in some test files per the documentation standards.

See #52628.

#6 @johnbillion
8 months ago

In 50505:

Docs: Add examples of possible names for various hooks whose name contains a dynamic portion.

This provides greater discoverability of such hooks in search results on the Code Reference site as well as increased clarity when reading the source.

See #50734, #52628

#7 follow-up: @peterwilsoncc
8 months ago

In 50516:

Docs: Improve compatibility comment in WP_List_Table.

Improve comment explaining backward compatibility check for the primary column in WP_List_Table::get_column_info().

Unprops helen, markjaquith.
See #52628, #34564.

#8 in reply to: ↑ 7 @jeremyfelt
8 months ago

Replying to peterwilsoncc:

In 50516:

"added as a forth item" should be "added as a fourth item" :)

#9 @peterwilsoncc
8 months ago

In 50517:

Docs: Improve spelling in [50516].

Props jeremyfelt.
See #52628, #34564.

#10 @SergeyBiryukov
8 months ago

In 50531:

Docs: Correct DocBlock formatting for register_block_style_handle().

Follow-up to [48141].

See #52628.

#11 @SergeyBiryukov
8 months ago

In 50532:

Docs: Synchronize $category_name description in WP_Block_Pattern_Categories_Registry methods.

Follow-up to [48156].

See #52628.

#12 @SergeyBiryukov
7 months ago

In 50562:

Docs: Fix typo in pre_term_link filter description.

See #52628.

#14 @davidbaumwald
7 months ago

Thanks for the patch, @sabernhardt. I found another instance of $htmlhint being improperly described in another docblock on line 3537 in wp-includes/general-template.php. I'll address that one as well in the commit that follows.

#15 @davidbaumwald
7 months ago

In 50583:

Docs: Fix description for $htmlhint argument in code editor settings.

Introduced in [41558].

Props sabernhardt.
See #52628.

#16 @SergeyBiryukov
7 months ago

In 50610:

Docs: Spell "non-existent" in a consistent way.

See #52628.

#17 @SergeyBiryukov
6 months ago

In 50781:

Docs: Add a @since note to wp_mail() about using is_email() for validation.

Follow-up to [48645].

See #52628.

#18 @ocean90
6 months ago

[49597] has limited the return type of wp_get_object_terms() to only arrays of type WP_Term. But depending on the fields argument other array types are supported too. For example int[] in case of 'fields' => 'ids'. Same for the filters in the function.

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


6 months ago

#20 @alexstine
6 months ago

Added 52628.class-walker-page.diff to fix an incorrect comment from #43522 (r42808).

#21 @SergeyBiryukov
6 months ago

In 50823:

Docs: Correct the aria-current array key in the documentation for two widget filters.

This applies to nav_menu_link_attributes and page_menu_link_attributes filters.

Follow-up to [42808], [44416].

Props jnylen0, chetan200891, alexstine.
See #43522, #52628.

#22 @johnbillion
6 months ago

In 50828:

Docs: Miscellaneous docblock updates.

See #52628

This ticket was mentioned in PR #1242 on WordPress/wordpress-develop by bahiirwa.


6 months ago

  • Keywords has-patch added

This was skipped in the review for https://core.trac.wordpress.org/changeset/48315
A simple typo.

PS: I don't know how to handle this. I have reported this to https://core.trac.wordpress.org/ticket/52628

#24 @laurencebahiirwa
6 months ago

This was skipped in the review for https://core.trac.wordpress.org/changeset/48315

A simple typo. I have made a PR via https://github.com/WordPress/wordpress-develop/pull/1242. I do not know if that's the right space.

#25 @SergeyBiryukov
6 months ago

In 50831:

Docs: Correct @since tags for new properties and functions related to infinite scrolling in Media Library.

Follow-up to [50829].

See #50105, #40330, #52628.

#26 @SergeyBiryukov
5 months ago

In 50912:

Docs: Clarify the @since note for unlink-homepage-logo in get_custom_logo().

This should make it clearer that the value applies to the custom-logo theme feature.

Follow-up to [48039], [48283], [48749], [48757], [48758], [48832].

Props joyously.
See #51075, #52628.

#27 @SergeyBiryukov
5 months ago

In 50913:

Docs: Update documentation in phpunit/includes/abstract-testcase.php per the documentation standards.

Follow-up to [44902].

See #52628.

#28 @SergeyBiryukov
5 months ago

In 50916:

Docs: Miscellaneous DocBlock corrections.

See #52628.

#29 @SergeyBiryukov
5 months ago

In 50918:

Docs: Update documentation in wp-config-sample.php per the documentation standards.

See #52628.

#30 @SergeyBiryukov
5 months ago

In 50952:

Docs: Use 3-digit, x.x.x-style semantic versioning for two _doing_it_wrong() calls.

Follow-up to [37985], [38420], [39021].

See #52628.

#31 @SergeyBiryukov
5 months ago

In 51055:

Docs: Add a @since note to wp_parse_id_list() and wp_parse_slug_list() about using wp_parse_list().

Follow-up to [44546], [49941].

Props joyously, dlh, pbiron.
See #52628.

#32 @SergeyBiryukov
5 months ago

In 51138:

Docs: Correct DocBlock formatting for some revision tests.

Follow-up to [50949], [51124].

See #52628.

#33 @SergeyBiryukov
4 months ago

In 51142:

Docs: Update documentation for some WP_Customize_Widgets methods per the documentation standards.

  • Add missing @since tags for the $id_base parameter of ::sanitize_widget_instance() and ::sanitize_widget_js_instance()`.
  • Document the usage of $wp_widget_factory global in ::sanitize_widget_instance().
  • Use multi-line comment syntax for a comment in ::enqueue_scripts().

Follow-up to [50996], [51141].

See #52628.

#34 @desrosj
4 months ago

Opened #53399 for the 5.9 cycle.

#35 @SergeyBiryukov
4 months ago

In 51150:

Docs: Document the usage of $_wp_current_template_content global in a few block template functions.

Follow-up to [51003], [51149].

See #52628.

#36 @SergeyBiryukov
4 months ago

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

In 51151:

Docs: Document the usage of $wp_embed global in WP_oEmbed_Controller::get_proxy_item().

Follow-up to [48135].

Fixes #52628.

#37 @SergeyBiryukov
4 months ago

In 51152:

Docs: Document the VALID_ORIGINS constant in WP_Theme_JSON.

Follow-up to [51149].

See #52628.

#38 @SergeyBiryukov
4 months ago

In 51157:

I18N: Use consistent pattern for placeholder references in translator comments for some bundled theme strings.

Follow-up to [42827], [44562], [50234].

See #52628.

#39 @SergeyBiryukov
4 months ago

In 51159:

Docs: Add missing documentation for wp_migrate_old_typography_shape().

Follow-up to [51089].

See #52991, #52628.

#40 @SergeyBiryukov
4 months ago

In 51168:

Docs: Update syntax for some multi-line comments per the documentation standards.

Follow-up to [51003], [51149].

See #52628.

#41 @SergeyBiryukov
4 months ago

In 51185:

Docs: Correct DocBlock formatting for Core_Upgrader::upgrade().

Document the $auto_update_settings parameter of the after_core_auto_updates_settings action.

Follow-up to [49254].

See #52628.

#42 @SergeyBiryukov
4 months ago

In 51188:

Docs: Correct @since version in the wp-includes/version.php file header.

There was no public release of WordPress 1.1.

Follow-up to [803], [43662].

See #52628.

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


4 months ago

#44 @SergeyBiryukov
4 months ago

In 51279:

Docs: Document the globals used in WP_REST_Widget_Types_Controller and WP_REST_Widgets_Controller.

Follow-up to [50995].

See #52628, #53461.

#45 @SergeyBiryukov
4 months ago

In 51280:

Docs: Add missing @since tags for some REST API methods added in 5.8.

Follow-up to [50995], [51021].

See #52628, #53461.

#46 @SergeyBiryukov
4 months ago

In 51281:

Docs: Add @ticket references to some WP_Theme_JSON tests.

Follow-up to [50973], [51054].

See #52628, #53461.

#47 @SergeyBiryukov
4 months ago

In 51282:

Docs: Adjust wp_dashboard_browser_nag() DocBlock per the documentation standards.

Follow-up to [51117], [51119], [51120].

See #52628, #53461.

#48 @SergeyBiryukov
4 months ago

In 51283:

Docs: Add missing @since tags for some WP_Theme_JSON methods.

Docs: Update syntax for multi-line comments per the documentation standards.

Follow-up to [50959], [50967], [50973], [51051], [51089], [51149].

See #52628, #53461.

#49 @SergeyBiryukov
4 months ago

In 51284:

Docs: Improve documentation for optional parameters in WP_Theme_JSON_Resolver methods per the documentation standards.

Move add_action() call to wp-includes/default-filters.php.

Follow-up to [50959], [51221].

See #52628, #53461.

#50 @SergeyBiryukov
4 months ago

In 51286:

Docs: List the expected type first instead of WP_Error in some REST API methods added in 5.8.

Follow-up to [46696], [49929], [50995], [51021].

See #52628, #53461.

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


4 months ago

#52 @SergeyBiryukov
4 months ago

In 51289:

Docs: Remove an empty line between @param and @return tags in some newly added REST API methods, per the documentation standards.

Follow-up to [48242], [49925], [51003], [51021].

See #52628, #53461.

#53 @SergeyBiryukov
4 months ago

In 51292:

Docs: Improve documentation for optional parameters in WP_Theme_JSON methods per the documentation standards.

Additionally:

  • Remove an empty line between @param and @return tags.
  • Correct alignment of @param tags.

Follow-up to [50959], [50973], [51149], [51284], [51289].

See #52628, #53461.

#54 @SergeyBiryukov
4 months ago

In 51294:

Twenty Twenty-One: Improve documentation per the documentation standards:

  • Remove unnecessary @access tags that were previously removed from core.
  • Remove an empty line between @param and @return tags.
  • Correct alignment of @param tags.

Follow-up to [41161], [41162], [41168], [49216], [49220].

See #52628, #53461.

#55 @SergeyBiryukov
4 months ago

In 51304:

Twenty Twenty-One: Add missing documentation for some filters.

Add missing @since tags for some functions.

Follow-up to [49216], [49220], [49854], [51294].

See #52628, #53461.

#56 @desrosj
4 months ago

  • Keywords commit dev-feedback added
  • Resolution fixed deleted
  • Status changed from closed to reopened

Reopening to backport.

#57 @desrosj
4 months ago

In 51310:

Docs: Document the globals used in WP_REST_Widget_Types_Controller and WP_REST_Widgets_Controller.

Follow-up to [50995].

Props SergeyBiryukov.
Merges [51279] to the 5.8 branch.
See #52628, #53461.

#58 @desrosj
4 months ago

In 51311:

Docs: Add missing @since tags for some REST API methods added in 5.8.

Follow-up to [50995], [51021].

Props SergeyBiryukov.
Merges [51280] to the 5.8 branch.
See #52628, #53461.

#59 @desrosj
4 months ago

In 51312:

Docs: Add @ticket references to some WP_Theme_JSON tests.

Follow-up to [50973], [51054].

Props SergeyBiryukov.
Merges [51280] to the 5.8 branch.
See #52628, #53461.

#60 @desrosj
4 months ago

In 51313:

Docs: Adjust wp_dashboard_browser_nag() DocBlock per the documentation standards.

Follow-up to [51117], [51119], [51120].

Props SergeyBiryukov.
Merges [51282] to the 5.8 branch.
See #52628, #53461.

#61 @desrosj
4 months ago

In 51314:

Docs: Add missing @since tags for some WP_Theme_JSON methods.

Docs: Update syntax for multi-line comments per the documentation standards.

Follow-up to [50959], [50967], [50973], [51051], [51089], [51149].

Props SergeyBiryukov.
Merges [51283] to the 5.8 branch.
See #52628, #53461.

#62 @desrosj
4 months ago

In 51315:

Docs: Improve documentation for optional parameters in WP_Theme_JSON_Resolver methods per the documentation standards.

Move add_action() call to wp-includes/default-filters.php.

Follow-up to [50959], [51221].

Props SergeyBiryukov.
Merges [51284] to the 5.8 branch.
See #52628, #53461.

#63 @desrosj
4 months ago

In 51316:

Docs: List the expected type first instead of WP_Error in some REST API methods added in 5.8.

Follow-up to [46696], [49929], [50995], [51021].

Props SergeyBiryukov.
Merges [51286] to the 5.8 branch.
See #52628, #53461.

#64 @desrosj
4 months ago

In 51317:

Docs: Remove an empty line between @param and @return tags in some newly added REST API methods, per the documentation standards.

Follow-up to [48242], [49925], [51003], [51021].

Props SergeyBiryukov.
Merges [51289] to the 5.8 branch.
See #52628, #53461.

#65 @desrosj
4 months ago

In 51318:

Docs: Improve documentation for optional parameters in WP_Theme_JSON methods per the documentation standards.

Additionally:

  • Remove an empty line between @param and @return tags.
  • Correct alignment of @param tags.

Follow-up to [50959], [50973], [51149], [51284], [51289].

Props SergeyBiryukov.
Merges [51292] to the 5.8 branch.
See #52628, #53461.

#66 @desrosj
4 months ago

In 51319:

Twenty Twenty-One: Improve documentation per the documentation standards:

  • Remove unnecessary @access tags that were previously removed from core.
  • Remove an empty line between @param and @return tags.
  • Correct alignment of @param tags.

Follow-up to [41161], [41162], [41168], [49216], [49220].

Props SergeyBiryukov.
Merges [51294] to the 5.8 branch.
See #52628, #53461.

#67 @desrosj
4 months ago

In 51320:

Twenty Twenty-One: Add missing documentation for some filters.

Add missing @since tags for some functions.

Follow-up to [49216], [49220], [49854], [51294].

Props SergeyBiryukov.
Merges [51304] to the 5.8 branch.
See #52628, #53461.

#68 @desrosj
4 months ago

  • Keywords dev-reviewed added; dev-feedback removed
  • Resolution set to fixed
  • Status changed from reopened to closed

All changes have been backported. If more are needed, we can reopen to backport those.

#69 @SergeyBiryukov
4 months ago

In 51322:

Twenty Twenty: Add missing documentation for some filters.

Add missing @since tags for some functions.

Correct alignment of some @param tags.

Follow-up to [46271], [46278], [51304].

See #52628, #53461.

#70 @SergeyBiryukov
4 months ago

In 51323:

Bundled Themes: Correct @since tags for block patterns.

Follow-up to [49347], [49348], [49583], [49584], [49763], [51103].

See #52628, #53461.

#71 @SergeyBiryukov
4 months ago

In 51324:

Docs: Correct @see references for hooks in the get_option() description.

Follow-up to [51050].

See #52628, #53461.

#72 @desrosj
4 months ago

In 51338:

Twenty Twenty: Add missing documentation for some filters.

Add missing @since tags for some functions.

Correct alignment of some @param tags.

Follow-up to [46271], [46278], [51304].

Props SergeyBiryukov.
Merges [51322] to the 5.8 branch.
See #52628, #53461.

#73 @desrosj
4 months ago

In 51339:

Bundled Themes: Correct @since tags for block patterns.

Follow-up to [49347], [49348], [49583], [49584], [49763], [51103].

Props SergeyBiryukov.
Merges [51324] to the 5.8 branch.
See #52628, #53461.

#74 @desrosj
4 months ago

In 51340:

Docs: Correct @see references for hooks in the get_option() description.

Follow-up to [51050].

Props SergeyBiryukov.
Merges [51324] to the 5.8 branch.
See #52628, #53461.

Note: See TracTickets for help on using tickets.