Make WordPress Core

Opened 2 years ago

Closed 2 years ago

Last modified 2 years ago

#54729 closed task (blessed) (fixed)

Docblock improvements for WP 6.0

Reported by: hellofromtonya's profile hellofromTonya Owned by:
Milestone: 6.0 Priority: normal
Severity: normal Version:
Component: General Keywords: has-patch
Focuses: docs Cc:

Description

Previously:

Attachments (3)

54729.diff (3.3 KB) - added by azouamauriac 2 years ago.
in src/wp-includes/class-wp-user.php use third person in function docblock
54729.2.diff (6.5 KB) - added by azouamauriac 2 years ago.
in src/wp-includes/post-template.php and src/wp-includes/post-thumbnail-template.php use third person in function docblock
54729.3.diff (17.2 KB) - added by azouamauriac 2 years ago.
Use third-person singular verbs for function descriptions in src/wp-includes/class-wp-customize-manager.php

Download all attachments as: .zip

Change History (108)

This ticket was mentioned in Slack in #core-coding-standards by jrf. View the logs.


2 years ago

This ticket was mentioned in PR #2173 on WordPress/wordpress-develop by kebbet.


2 years ago
#2

  • Keywords has-patch added

Typos in misc. docblocks.

Trac ticket: https://core.trac.wordpress.org/ticket/54729

#3 @audrasjb
2 years ago

Self assigning PR2173 for commit. Thanks @kebbet 🙌

#4 @audrasjb
2 years ago

In 52582:

Docs: Miscellaneous docblock corrections in REST API and Sitemaps API.

Props kebbet.
See #54729.

This ticket was mentioned in PR #2176 on WordPress/wordpress-develop by kebbet.


2 years ago
#6

Typos in misc. docblocks.

Trac ticket: https://core.trac.wordpress.org/ticket/54729

kebbet commented on PR #2176:


2 years ago
#7

The two reverted changes are reported upstream in https://github.com/WordPress/gutenberg/pull/38048

#8 @SergeyBiryukov
2 years ago

In 52597:

Docs: Fix typos in some DocBlocks.

Props kebbet.
See #54729.

#10 @johnbillion
2 years ago

In 52652:

Docs: Increase the specificity of types in various inline documentation.

See #54729

This ticket was mentioned in PR #2265 on WordPress/wordpress-develop by kebbet.


2 years ago
#11

Use correct function name in DocBlock for wp_kses_attr.

Trac ticket: https://core.trac.wordpress.org/ticket/54729

#12 @audrasjb
2 years ago

In 52680:

Docs: Typo corrections in various API docblocks.

Props hasanuzzamanshamim.
Fixes #55073.
See #54729.

This ticket was mentioned in PR #2293 on WordPress/wordpress-develop by kebbet.


2 years ago
#13

Spell overridden with two d's
https://core.trac.wordpress.org/ticket/54729

#14 follow-up: @audrasjb
2 years ago

In 52692:

Docs: Typo correction in class-wp-theme-json docblocks.

Props kebbet.
See #54729.

#16 @audrasjb
2 years ago

In 52693:

Docs: Fix an error in wp_kses_attr() docblock.

Props kebbet.
See #54729.

#18 @SergeyBiryukov
2 years ago

In 52703:

Docs: Update DocBlocks for some object cache functions per the documentation standards.

Follow-up to [47060], [47938], [47944], [52700].

See #54729, #54574.

#19 @SergeyBiryukov
2 years ago

In 52704:

Docs: Correct @since tag for wp_cache_reset().

The function was added in WordPress 3.0, not 2.6.

Follow-up to [13066].

See #54729.

#20 @SergeyBiryukov
2 years ago

In 52705:

Docs: Correct the suggested alternative for the deprecated wp_cache_reset() function.

While this was previously added and reverted more than once as part of various documentation cleanup efforts, wp_cache_switch_to_blog() appears to be the correct alternative for wp_cache_reset(), per the latter's DocBlock.

This commit also corrects the @deprecated tag for WP_Object_Cache::reset() to link to the ::switch_to_blog() method of the class, instead of the function of the same name.

Follow-up to [13066], [21403], [22111], [33678], [34225], [34226], [40929].

See #54729.

#21 @SergeyBiryukov
2 years ago

In 52708:

Docs: Improve @return tags for wp_cache_*_multiple() functions:

  • wp_cache_add_multiple()
  • wp_cache_set_multiple()
  • wp_cache_get_multiple()
  • wp_cache_delete_multiple()

This aims to provide more details about the returned value types.

Follow-up to [52700], [52702], [52703].

See #54729, #54574.

#22 in reply to: ↑ 14 @hellofromTonya
2 years ago

  • Keywords dev-reviewed commit added

Replying to audrasjb:

In 52692:

Docs: Typo correction in class-wp-theme-json docblocks.

Props kebbet.
See #54729.

To resolve a backport conflict for 5.9.1 (in backporting [52757] to 5.9 branch), marking r52692 as reviewed and approved for backport to 5.9 branch. In doing this additional backport, the changeset 1:1 relationship is retained.

Last edited 2 years ago by hellofromTonya (previous) (diff)

#23 @audrasjb
2 years ago

In 52758:

Docs: Typo corrections in class-wp-theme-json docblocks.

Props kebbet, hellofromtonya.
Merges [52692] to the 5.9 branch.
See #54729.

#24 @hellofromTonya
2 years ago

  • Keywords has-patch dev-reviewed commit removed

Resetting the keywords after r52758.

#25 @SergeyBiryukov
2 years ago

In 52776:

Docs: Improve some DocBlocks in wp_validate_boolean() tests for consistency.

Follow-up to [46159], [46224], [52775].

See #54725, #54729.

#26 @SergeyBiryukov
2 years ago

In 52777:

Docs: Correct parameter types for data_wp_validate_boolean().

Follow-up to [46159], [46224], [52775], [52776].

See #54725, #54729.

#27 @SergeyBiryukov
2 years ago

In 52779:

Docs: Fix typo in TracTickets::isTracTicketClosed() description.

Follow-up to [761/tests], [762/tests], [891/tests].

See #54729.

#28 @audrasjb
2 years ago

In 52793:

Docs: Correct return type for get_block_metadata_i18n_schema().

Props jeremyfelt.
Fixes #55243.
See #54729.

#29 @audrasjb
2 years ago

In 52795:

Docs: Correct return type for get_post_custom().

Props chouby, audrasjb.
Fixes #55249.
See #54729.

#30 @SergeyBiryukov
2 years ago

In 52810:

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

See #54729.

#31 @SergeyBiryukov
2 years ago

In 52821:

Docs: Add inline comments for non-visible characters in sanitize_title_with_dashes().

This aims to clarify the list of characters that are stripped from URLs or converted to a hyphen.

Follow-up to [51984].

See #47912, #54729.

@azouamauriac
2 years ago

in src/wp-includes/class-wp-user.php use third person in function docblock

This ticket was mentioned in PR #2382 on WordPress/wordpress-develop by audrasjb.


2 years ago
#32

  • Keywords has-patch added

#33 @audrasjb
2 years ago

Thanks @azouamauriac, I'll commit this patch right now 👍

#35 @audrasjb
2 years ago

In 52827:

Docs: Use third-person singular verbs for function descriptions in wp-includes/class-wp-user.php.

Props azouamauriac.
See #54729.

#36 @audrasjb
2 years ago

In 52930:

Docs: Use third-person singular verbs for function descriptions in wp-includes/class-wp-locale.php.

Follow-up to [52929].

See #54729.

#37 @audrasjb
2 years ago

In 52931:

Docs: Miscellaneous fixes in wp-admin/includes/plugin-install.php and wp-admin/includes/plugin.php.

See #54729.

#38 @SergeyBiryukov
2 years ago

In 52934:

Docs: Further clarify the description for install_dashboard().

Follow-up to [52931].

See #54729.

@azouamauriac
2 years ago

in src/wp-includes/post-template.php and src/wp-includes/post-thumbnail-template.php use third person in function docblock

#39 follow-up: @audrasjb
2 years ago

Thanks @azouamauriac, self assigning 54729.2.diff for review/commit.

#40 in reply to: ↑ 39 @azouamauriac
2 years ago

Replying to audrasjb:

Thanks @azouamauriac, self assigning 54729.2.diff for review/commit.

Thanks.👍

#41 @audrasjb
2 years ago

In 52935:

Docs: Misc. fixes in wp-includes/post-template.php and wp-includes/post-thumbnail-template.php.

Props azouamauriac, audrasjb.
See #54729.

#42 @SergeyBiryukov
2 years ago

In 52941:

Docs: Add a @since note about Twenty Twenty-Two for WP_Theme::$default_themes.

Follow-up to [51328], [52093].

See #54729.

#43 @peterwilsoncc
2 years ago

In 52943:

Editor/Docs: Add blockTypes argument to WP_Block_Patterns_Registry::register() docblock.

Add the optional blockTypes argument in the patten properties for WP_Block_Patterns_Registry::register().

Props vlad.olaru.
Fixes #55303.
See #54729.

#44 @SergeyBiryukov
2 years ago

In 52959:

Docs: Correct variable references in get_category_feed_link() and get_term_feed_link() @return tags.

The $cat_id and $term_id variables were replaced by $cat and $term, respectively.

Follow-up to [52180].

See #54729.

#45 @SergeyBiryukov
2 years ago

In 52984:

Docs: Adjust documentation in get_post_galleries() tests per the documentation standards.

Follow-up to [52190], [52797].

Props azouamauriac, SergeyBiryukov.
See #54725, #54729.

#46 @SergeyBiryukov
2 years ago

In 52992:

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

See #54729.

#47 @audrasjb
2 years ago

In 52994:

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

See #54729.

#48 @audrasjb
2 years ago

In 52999:

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

See #54729.

#49 @johnbillion
2 years ago

In 53000:

Docs: Correct the documented return types for date and time related functions and filters.

See #54729

#50 @audrasjb
2 years ago

In 53002:

Docs: Use third-person singular verbs for function descriptions in wp-admin/includes/theme.php and wp-admin/includes/theme-install.php, per the documentation standards.

See #54729.

#51 @costdev
2 years ago

Related: #55493

#52 @SergeyBiryukov
2 years ago

In 53040:

Docs: Add missing descriptions for WP_List_Table::get_items_per_page() parameters.

Follow-up to [53039].

Props jrf, aristath, poena, justinahinon, SergeyBiryukov.
See #54729, #55327.

#54 @audrasjb
2 years ago

In 53046:

Docs: Use third-person singular verbs for function descriptions in WP_Embed class, per the documentation standards.

See #54729.

@azouamauriac
2 years ago

Use third-person singular verbs for function descriptions in src/wp-includes/class-wp-customize-manager.php

#55 @audrasjb
2 years ago

In 53054:

Docs: Use third-person singular verbs for function descriptions in WP_Customize_Manager class, per the documentation standards.

Props azouamauriac.
See #54729.

#56 @audrasjb
2 years ago

In 53055:

Docs: Use third-person singular verbs for function descriptions in WP_Customize_Nav_Menus class, per the documentation standards.

Follow-up to [53054].

See #54729.

#57 @SergeyBiryukov
2 years ago

In 53056:

Docs: Use correct format for multi-line comments in the_block_editor_meta_boxes().

Follow-up to [44131], [44260].

See #54729.

#58 @SergeyBiryukov
2 years ago

In 53060:

Docs: Add missing description for $pagenow global in various functions.

See #54729, #55499.

#59 @SergeyBiryukov
2 years ago

In 53061:

Docs: Add missing description for $typenow global in various functions.

Follow-up to [53060].

See #54729.

#60 @SergeyBiryukov
2 years ago

In 53062:

Docs: Add missing description for $taxnow global in various functions.

Follow-up to [53060], [53061].

See #54729.

#61 @audrasjb
2 years ago

In 53064:

Docs: Use third-person singular verbs for function descriptions in WP_Automatic_Updater class, per the documentation standards.

See #54729.

#62 @SergeyBiryukov
2 years ago

In 53086:

Docs: Adjust some deprecated function DocBlocks per the documentation standards.

This ensures the replacement functions are linked correctly in the WordPress Code Reference.

Follow-up to [38515], [43548], [49992], [51348], [51586], [52757], [53082].

See #54729.

#63 @SergeyBiryukov
2 years ago

In 53087:

Docs: Adjust DocBlock formatting for wp_robots_*() and related functions.

This ensures the code blocks are displayed correctly in the WordPress Code Reference.

Follow-up to [19304], [37541], [44021], [49992].

See #54729.

#64 @audrasjb
2 years ago

In 53146:

Docs: Misc. docblock fixes in wp-admin/includes/mic.php, as per documentation standards.

See #54729.

#65 @audrasjb
2 years ago

In 53176:

Docs: Fix @link URLs in get_merged_data() Docblock.

This addresses some 404s found on Helphub links by replacing the related @link sources.

See #54729.

#66 @audrasjb
2 years ago

In 53177:

Docs: Small fixes in WP_Theme_JSON_Resolver docblocks, as per documentation standards.

See #54729.

#67 @audrasjb
2 years ago

In 53179:

Docs: Misc. Docblocks improvements in the Core User API.

See #54729.

#68 @audrasjb
2 years ago

In 53180:

Docs: Removes an irrelevant @link mention in Translation_Entry Class.

See #54729.

#69 @audrasjb
2 years ago

In 53189:

Docs: Use third-person singular verbs for function descriptions in author-template.php, as per documentation standards.

See #54729.

#70 @SergeyBiryukov
2 years ago

In 53194:

Docs: Add missing documentation for add_cssclass() and add_menu_classes().

Follow-up to [9578], [53193].

See #54729.

#71 @SergeyBiryukov
2 years ago

In 53200:

Docs: Add missing descriptions for function parameters in wp-admin/includes/meta-boxes.php.

See #54729.

#72 @SergeyBiryukov
2 years ago

In 53201:

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

See #54729.

#73 @audrasjb
2 years ago

In 53202:

Docs: Update MDN link in send_frame_options_header() docblock.

The X-Frame-Options MDN documentation has been moved to /docs/Web/HTTP/Headers/X-Frame-Options. This changeset updates the link accordingly.

See #54729.

#74 @audrasjb
2 years ago

In 53204:

Docs: Update a link to the Custom Elements spec in force_balance_tags() docblock.

This changeset replaces a link to the outdated W3C specs on Custom Elements with a link to the corresponding WhatWG specification.

See #54729.

#75 @audrasjb
2 years ago

In 53205:

Docs: Update a link to the Custom Elements spec in unsupported_valid_tag_names() unit test docblock.

This changeset replaces a link to the outdated W3C specs on Custom Elements with a link to the corresponding WhatWG specification.

Follow-up to [53204].

See #54729.

#76 @audrasjb
2 years ago

In 53206:

Docs: Replace Codex links with the corresponding page on DevHub.

The Codex page for WP_Object_Cache already redirects to the corresponding DevHub page.

See #54729.

#77 @audrasjb
2 years ago

In 53229:

Docs: Misc fixes and improvements in the Administration Media API docblocks, as per documentation standards.

See #54729.

#79 @audrasjb
2 years ago

In 53235:

Docs: Docs: Use third-person singular verbs for function descriptions in wp-includes/blocks.php and wp-includes/script-loader.php, per the documentation standards.

See #54729.

#80 @SergeyBiryukov
2 years ago

In 53244:

Docs: Correct the expected parameter type for WP_Customize_Manager::remove_preview_signature().

Before the method was deprecated, the parameter contained the value passed through for the wp_die_handler filter, which expects a callable function.

Follow-up to [20926], [32535], [34320], [38810], [53242], [53243].

See #54729.

#81 @audrasjb
2 years ago

In 53248:

Docs: Use third-person singular verbs for function descriptions in Multisite WordPress API, as per docs standards.

See #54729.

#82 @audrasjb
2 years ago

In 53249:

Docs: Use third-person singular verbs for function descriptions in wp-includes/capabilities.php, as per docs standards.

Props azouamauriac.
See #54729.

#84 @audrasjb
2 years ago

In 53250:

Docs: Use third-person singular verbs for function descriptions in wp-includes/ms-load.php, as per docs standards.

See #54729.

#85 @audrasjb
2 years ago

In 53251:

Docs: Typo correction in wp-includes/ms-functions.php docblock.

See #54729.

#86 @audrasjb
2 years ago

In 53252:

Docs: Use third-person singular verbs for function descriptions in wp-includes/nav-menu.php, as per docs standards.

See #54729.

#87 @audrasjb
2 years ago

In 53254:

Docs: Use third-person singular verbs for function descriptions in WP_Theme Class, as per docs standards.

See #54729.

#88 @audrasjb
2 years ago

In 53256:

Docs: Use third-person singular verbs for function descriptions in WP_User_Query Class, as per docs standards.

See #54729.

#89 @audrasjb
2 years ago

In 53265:

Docs: Use third-person singular verbs for function descriptions in Core Comment API and Comment template functions.

See #54729.

#90 @SergeyBiryukov
2 years ago

In 53279:

Docs: Correct alignment for the customize_nav_menu_available_items filter DocBlock.

Follow-up to [53245].

See #54729.

#91 @SergeyBiryukov
2 years ago

In 53280:

Docs: Add missing documentation for WP_*_Query::get_search_sql() method parameters.

Includes renaming the $cols parameter to $columns for consistency across the classes.

Follow-up to [42876], [53272-53276].

See #54729.

#93 @johnbillion
2 years ago

In 53300:

Docs: Various docblock corrections.

See #54729

#94 @johnbillion
2 years ago

In 53301:

Mail: Improve the docblocks for actions and functions related to the parsing of authentication cookies.

See #54729

#95 @johnbillion
2 years ago

In 53302:

Docs: Various docblock corrections and improvements for changes introduced in 6.0.

See #54729

#97 @SergeyBiryukov
2 years ago

In 53314:

Docs: Adjust comments in Gruntfile.js per the documentation standards.

See #54729.

#98 @johnbillion
2 years ago

In 53316:

Docs: Corrections and improvements to docblocks for function and hooks relating to fatal error handling.

See #54729

#99 @johnbillion
2 years ago

In 53317:

Docs: Formatting corrections for various docblocks.

See #54729

#100 @johnbillion
2 years ago

In 53318:

Docs: Improve documentation of the walker argument for various functions.

See #54729

#101 @audrasjb
2 years ago

In 53323:

Docs: Docblock adjustements in the Walker class.

This changeset ensures third-person singular verbs are used for function descriptions in the Walker class, and adjusts some non-standard docblock descriptions for various properties and methods of the class.

See #54729.

#102 @audrasjb
2 years ago

In 53324:

Docs: Clarify the name and description of some parameters in the Walker class.

Follow-up to [53323].
See #54729.

#103 @costdev
2 years ago

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

With 6.0 RC1 tomorrow, closing this ticket.

If there are any more changes required between now and the final 6.0 release, this can be referenced and reopened if necessary with dev-reviewed.

#55646 is open for continuation during the 6.1 cycle.

#104 @SergeyBiryukov
2 years ago

In 53331:

Docs: Remove @return void from various DocBlocks.

Per the documentation standards, it should not be used outside of the default bundled themes.

Follow-up to [38767], [47055], [49697], [50956], [51003], [52069], [53255].

See #54729.

#105 @audrasjb
2 years ago

In 53332:

Docs: Correct parameter types for serialize_block() and serialize_blocks().

This changeset clarifies the expected type for the first parameter passed to serialize_block() and serialize_blocks() functions.

Props manooweb.
Fixes #55648.
See #54729.

Note: See TracTickets for help on using tickets.