Make WordPress Core

Opened 2 years ago

Closed 20 months ago

#56792 closed task (blessed) (fixed)

Docblock improvements for 6.2

Reported by: desrosj's profile desrosj Owned by:
Milestone: 6.2 Priority: normal
Severity: normal Version:
Component: General Keywords: has-patch has-unit-tests
Focuses: docs Cc:

Description (last modified by SergeyBiryukov)

Previously:

Change History (108)

#1 @SergeyBiryukov
2 years ago

  • Description modified (diff)

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


2 years ago
#2

  • Keywords has-patch added

#3 follow-up: @kebbet
2 years ago

There is no consensus on how to use behaviour and behavior in Core atm. Is this something that should be adressed/fixed?

#5 @SergeyBiryukov
2 years ago

In 54504:

Docs: Fix typo in a @since note for _get_cron_array().

Follow-up to [53791].

Props kebbet.
See #55646, #56792.

#6 @audrasjb
2 years ago

@kebbet we have a lot more "Behavior" occurrences than "Behaviour", so I'd say the current main consensus is "Behavior".

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


2 years ago
#7

  • Keywords has-unit-tests added

#8 in reply to: ↑ 3 @SergeyBiryukov
2 years ago

Replying to kebbet:

There is no consensus on how to use behaviour and behavior in Core atm. Is this something that should be adressed/fixed?

Per the spelling guidelines, American English should be preferred, so I think we should standardize on behavior.

#9 @kebbet
2 years ago

Thanks for making it clear @SergeyBiryukov!

I've added a PR with suggestions in PHP-files. I left out what i thought was included packages from others.
I've not touched CSS or JS files yet.

#10 @audrasjb
2 years ago

In 54505:

Docs: Inline comment typo correction in wp_image_file_matches_image_meta().

Props kebbet.
See #55646, #56792.

#11 follow-up: @desrosj
2 years ago

@kebbet could you open a new ticket for this?

I've taken a brief look, and seems there are a few other occurrences of -ise vs. -ize and -or vs. -our that we should correct all at once.

For example, I see a couple of colour where it should be color, one occurrence of organise (American English is organize). Would be good to take a full pass for any. I used this page as a reference.

This could loosely be categorized as coding standards, but I think it deserves it's own ticket to for discussion and easier reference later on.

#13 in reply to: ↑ 11 @kebbet
2 years ago

Replying to desrosj:

@kebbet could you open a new ticket for this?

Of course, #56811 was just created!

#14 @audrasjb
2 years ago

In 54655:

Docs: Add missing default parameter value in themes_api() docblock.

Props rezakhan995, costdev.
Fixes #56862.
See #56792.

#15 @audrasjb
2 years ago

In 54656:

Docs: Add missing default parameter value in trackback_response() docblock.

Props rakibwordpress, audrasjb, SergeyBiryukov.
Fixes #56867.
See #56792.

#16 @jorbin
2 years ago

In 54657:

Revert accidental 5.9 branch commits [54655] and [54656]

Unprops audrasjb.
See #56867, #56792, #56862, #56792.

#17 @jorbin
2 years ago

In 54658:

Docs: Add missing default parameter value in trackback_response() docblock.

Previously: [54656] [54657]

Props rakibwordpress, audrasjb, SergeyBiryukov.
Fixes #56867.
See #56792.

#18 @jorbin
2 years ago

In 54659:

Docs: Add missing default parameter value in themes_api() docblock.

Previously: [54655] [54657]

Props rezakhan995, costdev.
Fixes #56862.
See #56792.

#19 @audrasjb
2 years ago

In 54663:

Docs: Align spelling with American English.

This changeset replaces "behaviour" with "behavior" in various docblocks.

Props kebbet, jrf.
See #56811, #56792.

#21 @audrasjb
2 years ago

In 54664:

Docs: Align spelling with American English.

This changeset replaces "cancelled" with "canceled" in various docblocks, per the Spelling Guidelines.

Props costdev.
See #56811, #56792.

#22 @SergeyBiryukov
2 years ago

In 54727:

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.

Previously committed in [53205], this appears to be accidentally reverted in [53562].

Follow-up to [53204], [53205], [53562].

Props audrasjb.
See #56792.

#23 @audrasjb
2 years ago

Reported on DevHub by @aleksganev, about wp_dropdown_users().

In the “Parameters” section, in the description of “option_none_value”, the variable “$show_option_non” is misspelled and should be “$show_option_none”

The description in question:
“Value to use for $show_option_non when no users were found. Default -1.”

I'm going to commit a fix directly.

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

#24 @audrasjb
2 years ago

In 54738:

Docs: Typo correction in wp_dropdown_users() docblock.

Props aleksganev.
See #56792.

#25 @SergeyBiryukov
2 years ago

In 54741:

Docs: Update comments in wp_nav_menu() tests per the documentation standards.

Includes:

  • Fixing a few typos.
  • Using the correct format for multi-line comments.
  • Removing some comments that duplicate the assertion messages without providing any additional context.

Follow-up to [54478].

See #56792.

#26 @SergeyBiryukov
2 years ago

In 54747:

Docs: Add brackets to a function name in get_page_template() description.

This ensures the locate_block_template() function name is correctly linked in the Developer Reference.

Follow-up to [54179].

See #56792.

#27 @SergeyBiryukov
2 years ago

In 54755:

Docs: Correct DocBlock formatting for wp_sitemaps_enabled filter.

Follow-up to [48072], [48094], [48523].

See #56792.

#28 @audrasjb
2 years ago

In 54759:

Docs: Replace HTTP links with HTTPS in class-json.php docblocks.

Props haritpanchal.
Fixes #57017.
See #56792.

#29 @audrasjb
2 years ago

In 54775:

Docs: Replace HTTP links with HTTPS in class-pop3.php docblocks and JS vendor readme file.

Props rajeshraval786, hiren1094.
See #57017, #56792.

#30 @audrasjb
2 years ago

In 54776:

Docs: Fix block_editor_rest_api_preload() parameter type.

This changeset fixes the $preload_paths parameter type for block_editor_rest_api_preload() and related hooks. This parameter expects an array of strings OR an array where the path is the first element (index 0) of this array.

Props chouby.
Fixes #56810.
See #56792.

This ticket was mentioned in PR #3594 on WordPress/wordpress-develop by pkevan.


2 years ago
#31

The changes below are a follow on from previous work to improve docblocks information in code.

The PR contains a small number of changes from a list of missing values - each file has a single commit to allow for cherry-picking.

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

#32 @audrasjb
2 years ago

In 54794:

Docs: Improve globals documentation in unregister_taxonomy() and wp_term_is_shared().

Props upadalavipul, mukesh27.
Fixes #57058.
See #56792.

pkevan commented on PR #3594:


2 years ago
#33

Thanks for the review and feedback @costdev - i've committed the fixes and also picked up some more inconsistencies in my searching 😄

#34 @desrosj
2 years ago

In 54808:

Docs: Update comments in wp_nav_menu() tests per the documentation standards.

Includes:

  • Fixing a few typos.
  • Using the correct format for multi-line comments.
  • Removing some comments that duplicate the assertion messages without providing any additional context.

Follow-up to [54478].

Props SergeyBiryukov.
Merges [54741] to the 6.1 branch.
See #56792, #56946.

#35 @audrasjb
2 years ago

In 54833:

Docs: Various docblock fixes in Multisite administration functions.

See #56792.

#36 @audrasjb
2 years ago

In 54835:

Docs: Typo correction in get_registered_nav_menus() docblock.

Props nithins53.
Fixes #57101.
See #56792.

#37 @SergeyBiryukov
2 years ago

In 54842:

Docs: Minor DocBlock edits for get_adjacent_post() and related functions.

This aims to better match the line wrapping recommendations of the documentation standards.

Follow-up to [16951], [28111], [32606], [37254].

See #56792.

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


2 years ago
#38

Fix a typo in the PRESETS_METADATA constant description, in WP_Theme_JSON

https://core.trac.wordpress.org/ticket/56792

#39 @SergeyBiryukov
2 years ago

In 54853:

Docs: Fix typo in the WP_Theme_JSON::PRESETS_METADATA constant description.

Follow-up to [53129].

Props kebbet, mukesh27.
See #56792.

@SergeyBiryukov commented on PR #3627:


2 years ago
#40

Thanks for the PR! Merged in r54853.

#41 @SergeyBiryukov
2 years ago

In 54854:

Docs: Update wp_count_posts and wp_count_attachments filter descriptions.

This aims to match the wording generally used for other filters as per the documentation standards.

Follow-up to [25554], [25578], [25579], [53456].

See #56792.

#42 @SergeyBiryukov
2 years ago

In 54855:

Docs: Update various DocBlocks and inline comments per the documentation standards.

Includes minor formatting edits for consistency.

Follow-up to [53/tests], [12179], [12946], [35288], [37884], [38810], [38928], [46596], [48131], [52955], [53548], [53813], [53873], [54118], [54316], [54420], [54421], [54803].

See #56792.

#43 @SergeyBiryukov
2 years ago

In 54859:

Docs: Fix typo and improve DocBlock formatting in wp-admin/install-helper.php.

Follow-up to [236], [265], [8645], [30542].

See #56792.

#44 @audrasjb
2 years ago

In 54867:

Docs: Improve various globals documentation, as per documentation standards.

Props upadalavipul, mukesh27, krupalpanchal, jigar-bhanushali.
See #57069, #56792.

#45 @audrasjb
2 years ago

In 54868:

Docs: Improve various globals documentation, as per documentation standards.

Props upadalavipul.
See #57069, #56792.

#46 @audrasjb
2 years ago

In 54873:

Docs: Use third-person singular verbs for Block Supports related function descriptions, as per docblocks standards.

See #56792.

#47 @audrasjb
2 years ago

In 54874:

Docs: Various docblock fixes in Block Supports related functions.

See #56792.

#48 @audrasjb
2 years ago

In 54876:

Coding Standards: Fix brace indentation in wp-align/includes/noop.php.

Props alberuni-azad.
Fixes #57209.
See #56792.

#49 @audrasjb
2 years ago

In 54877:

Docs: Improve various globals documentation, as per documentation standards.

Props upadalavipul.
See #57069, #56792.

#50 @audrasjb
2 years ago

In 54883:

Docs: Add missing parameter descriptions in wp-admin/includes/template.php.

Props mahekkalola, costdev, audrasjb, riccardodicurti.
Fixes #57208.
See #56792.

#51 @audrasjb
2 years ago

In 54953:

Docs: Improve various globals documentation, as per documentation standards.

Props upadalavipul.
See #57069, #56792.

#52 @SergeyBiryukov
2 years ago

In 54954:

Docs: Add missing type for $_wp_theme_features in WP_Debug_Data::debug_data().

Includes moving the global declaration to the top of the method for consistency.

Follow-up to [44986], [54953].

See #57069, #56792.

#53 @SergeyBiryukov
2 years ago

In 54957:

Docs: Improve DocBlock formatting for get_post_class().

Follow-up to [9273], [27429], [31271], [37544].

See #56792.

#54 @SergeyBiryukov
2 years ago

In 54958:

Docs: Mark some optional parameters as such in wp-includes/comment-template.php.

This affects:

  • get_comment_class()
  • comment_class()
  • get_comment_excerpt()
  • comment_excerpt()
  • get_comment_link()
  • get_comment_text()
  • comment_text()
  • comments_open()
  • pings_open()
  • get_comment_reply_link()
  • comment_reply_link()
  • post_reply_link()
  • comment_form()

Follow-up to [25567], [27156], [33961].

See #56792.

#55 @audrasjb
2 years ago

In 55002:

Docs: Update docs for image_sideload_extensions filter to include webp in the list of allowed extensions.

Follow-up to [50810].

Props dimadin.
Fixes #57346.
See #56792.

#56 @audrasjb
23 months ago

In 55003:

Docs: Improve various globals documentation, as per docblock standards.

Props upadalavipul, audrasjb.

See #57069, #56792.

#57 @SergeyBiryukov
23 months ago

In 55004:

Twenty Seventeen: Document the $twentyseventeencounter global.

Follow-up to [38833], [38986], [55003].

See #57069, #56792.

#58 @SergeyBiryukov
23 months ago

In 55029:

Tests: Bring some consistency to mocking HTTP requests in unit tests.

Includes:

  • Renaming the $preempt parameter to $response in the pre_http_request filter to better match the context used in callbacks (returning the original value if the conditions are not met rather than preempting the request).
  • Synchronizing parameter names and types in various pre_http_request callbacks in unit tests.

Follow-up to [34509], [37907], [40628], [40629], [45667], [46175], [48242], [48462], [49904], [51021], [51973], [52146], [52382], [54043], [54968].

See #56793, #56792.

#59 @audrasjb
22 months ago

In 55043:

Docs: Align spelling with American English.

This changeset updates the use of "-ise" suffix to American English "-ize" in docblocks.

Follow-up to [54663], [54664].

Props ironprogrammer, costdev.
See #56811, #56792.

#60 @audrasjb
22 months ago

In 55044:

Docs: Align spelling with American English.

This changeset updates the use of "-ise" suffix to American English "-ize" and replaces "behaviour" with "behavior" in various docblocks.

Follow-up to [54663], [54664], [55043].

Props kebbet.
See #56811, #56792.

#61 @audrasjb
22 months ago

In 55051:

Docs: Align spelling with American English.

This changeset updates the use of "-ise" suffix to American English "-ize" in various files.

Follow-up to [54663], [54664], [55043], [55044].

Props kebbet, mukesh27.
See #56811, #56792.

#62 @audrasjb
22 months ago

In 55071:

Docs: Improve wp_style_add_data() function description.

This changeset removes an extra apostrophe in wp_style_add_data() DocBlock.

Props lanacodes, ashrafulsarkar, SergeyBiryukov.
Fixes #57466.
See #56792.

#63 @audrasjb
22 months ago

In 55072:

Docs: Use third-person singular verbs for Script Loader related function descriptions, as per docblocks standards.

See #56792.

#64 @audrasjb
22 months ago

In 55073:

Docs: Typo correction in POP3 class send_cmd() inline docs.

Props nitman43, manojkpatil, kebbet.
Fixes #57449.
See #56792.

#65 @audrasjb
22 months ago

In 55074:

Docs: Add a missing quote to wp_is_large_network() Docblock params.

Props lanacodes.
Fixes #57468.
See #56792.

#66 @audrasjb
22 months ago

In 55075:

Docs: Various docblock fixes in Multisite WordPress API related functions.

Follow-up to [55074].

See #56792.

#67 @audrasjb
22 months ago

In 55080:

Docs: Remove unused post_modified and post_modified_gmt params from wp_insert_post() docblock.

Props dshanske, mehulkaklotar.
Fixes #57473.
See #56792.

@audrasjb commented on PR #3594:


22 months ago
#68

I just noticed that we forgot this PR.
@pkevan could you please resolve the two small conflicts, so we can commit this PR?
Thanks!

pkevan commented on PR #3594:


22 months ago
#69

no problem @audrasjb - the conflicts should be resolved.

#70 @audrasjb
22 months ago

In 55123:

Docs: Various improvements in ms-blogs.php function descriptions, as per docblocks standards.

See #56792.

#71 @SergeyBiryukov
22 months ago

In 55128:

Docs: Add missing @since tag for WP_Theme_JSON_Resolver::remove_json_comments().

Follow-up to [54162].

See #56792.

#72 @hellofromTonya
22 months ago

In 55144:

Docs: Update $types param for wp_get_global_stylesheet().

In 6.1.0, the values the $types parameter accepts changed to include 'base-layout-styles'.

This commit updates the DocBlock to reflect this change and provide clear information of what the function will load if no types are passed to it.

Reference:

Follow-up to [54162], [52054].

Props oandregal, jorgefilipecosta , ntsekouras.
Fixes #57563.
See #56792.

#73 @johnbillion
22 months ago

In 55170:

Cron API: Improve the docs for some cron event and cron schedule related functions.

See #56792

#74 @SergeyBiryukov
22 months ago

In 55173:

Docs: Improve documentation for block pattern properties.

Includes:

  • Adding the templateTypes property to the WP_Block_Patterns_Registry::register() DocBlock.
  • Adding @since notes for the postTypes and templateTypes properties to:
    • _register_theme_block_patterns()
    • WP_Block_Patterns_Registry::register()
  • Bringing some consistency to the order of properties between:
    • _register_theme_block_patterns()
    • WP_Block_Patterns_Registry::register()
    • WP_REST_Block_Patterns_Controller::prepare_item_for_response()
    • WP_REST_Block_Patterns_Controller::get_item_schema()

Follow-up to [52943], [53152], [54263], [55168].

See #56792.

#75 @SergeyBiryukov
22 months ago

In 55174:

Docs: Document the inserter property in WP_Block_Patterns_Registry::register().

Follow-up to [53152], [55173].

See #56792.

#76 @SergeyBiryukov
22 months ago

In 55202:

Docs: Improve the DocBlock for get_attached_file().

Includes:

  • Using 3-digit format for the @since tag.
  • Minor wording updates and formatting corrections.

Follow-up to [3203], [4612], [6379], [8203], [24983], [29090], [55199].

See #51780, #56792.

#77 @SergeyBiryukov
22 months ago

In 55222:

Docs: Use consistent format for the @return tags in _wp_object_name_sort_cb() and _wp_object_count_sort_cb().

Both functions are used as a callback for uasort().

Follow-up to [36013], [55214].

See #57358, #56792.

#78 @johnbillion
21 months ago

In 55293:

Docs: Miscellaneous improvements and corrections to docblocks.

See #56792

#80 @audrasjb
21 months ago

In 55311:

Docs: Use third-person singular verbs for WP_Meta_Query related function descriptions, as per docblocks standards.

See #56792.

@mukesh27 commented on PR #4047:


21 months ago
#81

Thanks @costdev I can't find any other files in my search.

@mukesh27 commented on PR #4047:


21 months ago
#82

Thanks @costdev I can't find any other files in my search.

#83 @audrasjb
21 months ago

In 55316:

Docs: Various improvements in XML-RPC Class function descriptions, as per docblocks standards.

See #56792.

#85 @kebbet
21 months ago

PR 4079 sets the since version to 6.2.0 for all occurences of 6.1.2, beacause no 6.1.2 is released yet.

@audrasjb commented on PR #4079:


21 months ago
#86

Thanks for spotting this!
One related commit: https://core.trac.wordpress.org/changeset/55010

@mukesh27 commented on PR #4079:


21 months ago
#90

Thanks @kebbet for PR.

One move related commit: https://core.trac.wordpress.org/changeset/54894

@mukesh27 commented on PR #4079:


21 months ago
#91

Thanks @kebbet for PR.

One move related commit: https://core.trac.wordpress.org/changeset/54894

#92 @audrasjb
21 months ago

In 55349:

Docs: Use correct 6.2.0 @since version in multiple docblocks.

Props kebbet, audrasjb, mukesh27.
See #56792.

#94 @audrasjb
21 months ago

In 55355:

Docs: Replace HTTP with HTTPS in PHP Manual links located in wp-load.php.

Props shamimmiashuhagh.
See #56792.

#95 @audrasjb
21 months ago

In 55356:

Docs: Replace HTTP with HTTPS in PHP Manual links located in WP_Privacy_Policy_Content class.

Follow-up to [55355].

See #56792, #57017.

#96 @SergeyBiryukov
21 months ago

In 55363:

Docs: Add www. prefix to some PHP manual links in code comments.

This avoids an extra redirect and brings more consistency with other links to the PHP website in core.

Follow-up to [42980], [50914], [55355].

See #56792.

#97 @SergeyBiryukov
21 months ago

In 55393:

Tests: Remove duplicate DocBlock opening characters in tests/theme/wpTheme.php.

Follow-up to [814/tests], [904/tests], [50967].

Props mukesh27, costdev.
See #56792.

@SergeyBiryukov commented on PR #4047:


21 months ago
#98

Thanks for the PR! Merged in r55393.

#99 @SergeyBiryukov
21 months ago

In 55398:

Docs: Document default values for optional parameters in various DocBlocks.

Props paulkevan, costdev, audrasjb, SergeyBiryukov.
See #56792.

@SergeyBiryukov commented on PR #3594:


21 months ago
#100

Thanks for the PR! Merged in r55398 with some edits:

  • Clarified the actual behavior where appropriate, e.g. "Defaults to the current post author" instead of just "Default false".
  • Skipped a few instances of "Default empty array" when the array does in fact include some default values early in the function. Clarified those values where they were missing.

#101 @hellofromTonya
21 months ago

#57840 is now open for the ongoing Docblock improvements in the 6.3 cycle.

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


21 months ago

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


20 months ago

#104 @audrasjb
20 months ago

In 55472:

Bundled Themes: Improve various globals documentation, as per docblock standards.

Props viralsampat, audrasjb, costdev.
See #56792, #57069.

#105 @audrasjb
20 months ago

In 55485:

Docs: Add missing 6.2.0 @since mention in get_the_privacy_policy_link().

Follow-up to #55261.

See #56792, #56345.

#106 @audrasjb
20 months ago

In 55492:

Docs: Add security warning in remove_query_arg() docblock to make it consistent with add_query_arg().

Props roytanck.
Fixes #57885.
See #56792.

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


20 months ago

#108 @costdev
20 months ago

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

As we're about to enter RC, closing this ticket out for 6.2. If any changes are needed for backport to the 6.2 branch, feel free to reopen this ticket.

Note: See TracTickets for help on using tickets.