Docblock improvements for 7.0

[desrosj]

Previously:

• #63166 (6.9)
• #62281 (6.8)
• #61608 (6.7)
• #60699 (6.6)
• #59651 (6.5)
• #58833 (6.4)
• #57840 (6.3)
• #56792 (6.2)
• #55646 (6.1)
• #54729 (6.0)
• #53399 (5.9)
• #52628 (5.8)
• #51800 (5.7)
• #50768 (5.6)
• #49572 (5.5)
• #48303 (5.4)
• #47110 (5.3)
• #46543 (5.2)
• #42505 (5.1)
• #41017 (4.9)
• #39130 (4.8)
• #37770 (4.7)
• #32246 (4.6)

[westonruter]

In 61270:

Docs: Add missing descriptions and fix types for some @return tags.

Props huzaifaalmesbah, sabernhardt, westonruter.
See #64224.
Fixes #64262.

[SergeyBiryukov]

In 61275:

Docs: Improve description for wp_insert_post().

Follow-up to [6379], [8669].

Props rutujaparamane2004.
See #64224.

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

Thanks for the PR! Merged in r61275.

[westonruter]

In 61278:

Docs: Update meta box action documentation to more accurately reflect the possible object types.

In addition to a meta box being able to be added for a post, it can also be added for a comment or a link, or even nothing at all when on the Dashboard.

Props opr18, nikunj8866, soyebsalar01, westonruter.
See #64224.
Fixes #64251.

[westonruter]

In 61299:

Docs: Update various class @var tags to indicate nullability.

This updates various @var tags on class properties to correctly indicate that the props may be null or unset:

• WP_Dependencies::$all_queued_deps is nullable by both ::enqueue() and ::dequeue. Also, the types of the keys and values are specified.
• WP_Duotone::$global_styles_presets and ::$global_styles_block_names start off unset and are only initialized by static classes.
• WP_Query::init() and WP_Rewrite::init() are public methods that unset()s many class props.
• WP_Theme::cache_delete() sets many props to null.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/8953

Props justlevine, westonruter.
See #64238, #64224.

[westonruter]

In 61300:

Docs: Improve docblocks and types for WP_Screen properties.

• Correctly hint that WP_Screen::$_show_screen_options is null before being instantiated.
• Correctly hint that ::get_option(), get_help_tab() and get_screen_reader_text() can return null.
• Ensure $this->columns is an int, by casting $this->get_option( 'layout_columns', 'default' ) from its numeric string.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/8860

Props justlevine, peterwilsoncc, westonruter.
See #64238, #64224.

[westonruter]

In 61302:

Bundled Themes: Add missing @return tags and descriptions.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/10533

Props huzaifaalmesbah, sabernhardt, palak678, westonruter.
See #64224.
Fixes #64277.

[westonruter]

In 61309:

Twenty Eleven: Improve PHP docblocks with corrected descriptions, missing/corrected tags, and specific types.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/10482

Props huzaifaalmesbah, dhruvang21, juanfra, sabernhardt, noruzzaman, ravichudasama01, westonruter.
See #64224.
Fixes #64211.

### Description
This PR adds missing variable names to @param tags in Twenty Eleven, Twenty Ten, and Twenty Twenty themes.

### Changes
Twenty Eleven: category.php, functions.php
Twenty Ten: loop-attachment.php, author.php
Twenty Twenty: functions.php, inc/template-tags.php, template-parts/entry-header.php, template-parts/content-cover.php

### Testing Instructions

1. Navigate to the affected files.
2. Verify that the docblocks for the mentioned filters now include the variable names in the @param tags.
3. Ensure no PHP errors or warnings are generated.

[SergeyBiryukov]

In 61314:

Twenty Ten: Add missing variable names to some @param tags.

Follow-up to [25627].

Props huzaifaalmesbah.
See #64224.

[SergeyBiryukov]

In 61315:

Twenty Eleven: Add missing variable names to some @param tags.

Follow-up to [25625].

Props huzaifaalmesbah.
See #64224.

[SergeyBiryukov]

In 61317:

Twenty Twenty: Add missing variable names to some @param tags.

Follow-up to [46271], [46357], [51322].

Props huzaifaalmesbah.
See #64224.

[westonruter]

In 61319:

Twenty Twenty: Fix typo and improve param description for twentytwenty_read_more_tag().

Follow-up to [61302].

Props sabernhardt.
See #64277, #64224.

[westonruter]

In 61322:

Docs: Improve accuracy of wp_enqueue_classic_theme_styles() description.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/10565

Follow-up to [59980], [54687], [54358].

Props manhphucofficial, wildworks, sabernhardt, iflairwebtechnologies, westonruter.
See #61892, #64224.
Fixes #64317.

I have followed the testing instructions for Twenty Eleven, Twenty Ten, and Twenty Twenty.
The updated docblocks now include the missing parameter names ($html, $width, $height, $size, $elements, $post_types, $show_categories), and I’m not seeing any PHP warnings or notices.

This looks good to me and improves the clarity of the bundled theme docs.

## Description
Improves inline documentation for WP_Comments_List_Table in wp-admin/includes/class-wp-comments-list-table.php to align with WordPress coding standards.

## Changes

• Added missing summary descriptions.
• Improved specificity of @return and @param tags.

## Testing Instructions

1. Inspect src/wp-admin/includes/class-wp-comments-list-table.php.
2. Verify docblocks follow standards.

Thanks for the PR! Merged in r61314, r61315, and r61317.

Thanks for the update @huzaifaalmesbah! I have gone through the changes, and everything looks cleaner and much easier to follow now. The added descriptions and improved @return / @param details definitely make the docblocks more useful.
Nice improvement overall.

@westonruter Thank you for your review and suggestions. I’ve applied the changes you recommended.

## Description
This PR improves inline documentation in wp-admin files by adding missing parameter descriptions to function docblocks.

## Changes

• ✅ Added proper @param descriptions for functions missing them
• ✅ Added complete docblock for wp_load_press_this() function
• ✅ Enhanced function summary for wp_nav_menu_max_depth()
• ✅ All changes follow ​WordPress PHP Documentation Standards

## Files Modified

• wp-admin/install.php
• wp-admin/nav-menus.php
• wp-admin/update-core.php
• wp-admin/includes/ajax-actions.php
• wp-admin/includes/class-wp-importer.php

## Testing

• [x] No functional changes, documentation only
• [x] All parameter descriptions are accurate and follow WP standards

[SergeyBiryukov]

In 61356:

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

Follow-up to [32654].

Props rejaulalomkhan.
See #64224.

[SergeyBiryukov]

In 61380:

Docs: Update wp_get_media_creation_timestamp() DocBlock for consistency.

Follow-up to [19687], [41746].

See #64224.

[johnbillion]

In 61386:

Mail: Update some docblocks relating to inline email attachments.

See #28059, #64224

[johnbillion]

In 61387:

Docs: Miscellaneous improvements and corrections to inline documentation.

See #64224

[SergeyBiryukov]

In 61396:

Docs: Correct DocBlock formatting for png:IHDR.color-type-orig property test.

Follow-up to [60246].

Props mukesh27, adamsilverstein.
See #64224.

[westonruter]

In 61397:

Script Loader: Fix adding default version to script/style URL when args are supplied via enqueued handle.

Also fixes phpdoc for some member variables of WP_Scripts and WP_Styles.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/10608

Follow-up to [61358].

Props westonruter, peterwilsoncc.
See #64224, #64238.
Fixes #64372.

[johnbillion]

In 61406:

Upgrade/Install: Correct and improve various docblocks relating to upgrades.

See #64224

[SergeyBiryukov]

In 61412:

Docs: Improve description for add_settings_section().

Follow-up to [13177], [15180].

See #64224.

[westonruter]

In 61426:

Script Loader: Add types for arrays in phpdoc.

This resolves 10 missingType.iterableValue issues in PHPStan.

Follow-up to [61402], [61362], [61358].

See #64224, #64238.

[SergeyBiryukov]

In 61428:

Docs: Correct DocBlock formatting for rest_pre_serve_request filter.

Follow-up to [34928].

See #64224.

[johnbillion]

In 61449:

Docs: Correct the documented value ranges for query parameters relating to week numbers.

See #64224

[SergeyBiryukov]

In 61462:

Docs: Correct DocBlock formatting for a wp_update_comment_count_now() test.

Follow-up to [61336].

See #64224.

[westonruter]

In 61496:

Docs: Remove duplicated @see PHPDoc tag.

Follow-up to [59823].

Props marian1, showravhasan, sabernhardt, mukesh27.
See #61965, #64224.
Fixes #64515.

[johnbillion]

In 61505:

Docs: Remove redundant syntax from callable type declarations.

The parameter name is optional in PHPStan but not supported by Psalm. While neither tools are officially supported, this removes the parse error that Psalm users otherwise see.

See ​https://github.com/php-stubs/wordpress-stubs/issues/410 for some external discussion.

Props farhad0, marian1

See #64224

[SergeyBiryukov]

In 61508:

Docs: Add parameter descriptions for _wp_ajax_delete_comment_response().

Follow-up to [10204], [32652].

Props rejaulalomkhan, huzaifaalmesbah.
See #64224.

Hi @westonruter, I've made the changes you suggested. Thanks for your help!

[SergeyBiryukov]

In 61512:

Docs: Add missing parameter descriptions for get_cli_args().

Follow-up to [14760].

Props rejaulalomkhan, huzaifaalmesbah, westonruter, SergeyBiryukov.
See #64224.

[westonruter]

In 61520:

Docs: Add missing descriptions to wp_nav_menu_max_depth() and do_core_upgrade().

Developed in ​https://github.com/WordPress/wordpress-develop/pull/10570

Follow-up to [61512], [32642], [32654].

Props rejaulalomkhan, westonruter, huzaifaalmesbah.
See #64224.

Committed in r61520

[westonruter]

In 61521:

Docs: Add descriptions to docblocks in WP_Comments_List_Table.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/10569

Follow-up to [32642].

Props huzaifaalmesbah, westonruter, noruzzaman.
See #64224.

Committed in r61521 (​https://github.com/WordPress/wordpress-develop/commit/a5681c41f1e92943131df5dc4d71a57f459e0413)

Ticket: https://core.trac.wordpress.org/ticket/64224

# Changes

• class-wp-importer.php: Added missing file header.
• media.php: Fixed missing @param/@global descriptions and @return format.
• class-wp-list-table.php: Added missing summaries and fixed formatting.
• user.php: Added missing @param/@global descriptions.

[SergeyBiryukov]

In 61522:

Docs: Mark $delta parameter as optional in _wp_ajax_delete_comment_response().

Follow-up to [61508].

See #64224.

[SergeyBiryukov]

In 61523:

Docs: Expand file header for WP_Importer class.

Follow-up to [14760].

Props huzaifaalmesbah.
See #64224.

[SergeyBiryukov]

In 61524:

Docs: Add missing descriptions for WP_List_Table properties.

Follow-up to [31146], [35021].

Props huzaifaalmesbah.
See #64224.

[SergeyBiryukov]

In 61532:

Docs: Add missing descriptions for some admin media function parameters.

Follow-up to [7043], [7092], [8304], [9053], [21871].

Props huzaifaalmesbah.
See #64224.

Trac ticket: Core-64224.

This PR replaces an @see tag with @link in WP_REST_Global_Styles_Controller to align with WordPress PHP Inline Documentation Standards.

Tickets:
Trac Ticket #64224
Originally discussed in ​Gutenberg PR #74961

Changes:
Replaced @see with @link for the HTML specification URL.

[SergeyBiryukov]

In 61538:

Docs: Add missing descriptions for some user function parameters.

Follow-up to [32642], [32654], [34021].

Props huzaifaalmesbah.
See #64224.

Trac Ticket: https://core.trac.wordpress.org/ticket/64224

## Why this change?

This change aligns the codebase with the WordPress PHP Documentation Standards, which clearly distinguish between the intended usage of the @see and @link tags:

• @see is meant for referencing internal structural elements of the WordPress codebase, such as classes, functions, methods, or hooks.
• @link is meant for referencing external resources, including URLs, specifications, and tickets hosted outside the codebase.

Currently, there are several instances in WordPress core where @see is incorrectly used to reference:

• GitHub URLs
• Trac tickets
• External specifications (e.g. WHATWG specs)

This PR corrects those cases by replacing @see with @link where the reference points to an external resource.

## When to use @link

• External URLs Always use @link when referencing an external URL Example: @link https://html.spec.whatwg.org

• External resources Use @link for documentation, specifications, or tickets that live outside the WordPress codebase

## Contrast with @see

• Internal structure references Use @see when referring to:
  • Functions (e.g. @see wp_remote_get())
  • Classes (e.g. @see WP_Query)
  • Methods or hooks defined within WordPress core

## Detailed changes

This PR applies targeted fixes across 15 specific files in src/wp-admin and src/wp-includes, replacing incorrect @see tags with @link where appropriate.

### src/wp-admin

• edit-form-blocks.php
• site-editor.php

### src/wp-includes

• html-api/class-wp-html-active-formatting-elements.php
• html-api/class-wp-html-doctype-info.php
• html-api/class-wp-html-tag-processor.php
• html-api/class-wp-html-decoder.php
• class-wp-url-pattern-prefixer.php
• nav-menu-template.php
• pluggable.php
• media.php
• rest-api/endpoints/class-wp-rest-controller.php
• rest-api/endpoints/class-wp-rest-templates-controller.php
• script-loader.php
• speculative-loading.php
• deprecated.php

@huzaifaalmesbah Thanks for working on this cleanup!

The conversion from @see to @link for external URLs is correct and follows the WordPress documentation standards. However, for better consistency within this PR, I suggest adding a brief description after each @link URL, similar to what was done in src/wp-includes/html-api/class-wp-html-decoder.php

For example: * @link [URL] [Brief Description]

This would make the documentation more descriptive and maintain a uniform style across all the modified files in this PR.

Thanks for the PR! Merged in r61523, r61524, r61532, and r61538.

[johnbillion]

In 61546:

Docs: Document the contentOnly value for the $template_lock argument when registering a post type.

Props ocean90, mukesh27, johnbillion

See #64224

https://core.trac.wordpress.org/changeset/61546

[SergeyBiryukov]

In 61557:

Docs: Replace some @see tags with @link for URLs.

Follow-up to [58074], [61486].

Props huzaifaalmesbah, shailu25.
See #64224.

Thanks for the PR! Merged in r61557.

I had wondered about this, but @see seems to be OK for _either_ structural elements _or_ a URI. See ​https://docs.phpdoc.org/guide/references/phpdoc/tags/see.html (pun intended)

Thanks for pointing this out @westonruter !
You’re right. phpDocumentor does allow using @see with a URI as well.

However, according to the [WordPress PHP Documentation Standards](​https://developer.wordpress.org/coding-standards/inline-documentation-standards/php/#1-functions-class-methods
) for DocBlocks:

👉 URLs should be added with the @link tag.

Specifically, the handbook states:

*@link: URL that provides more information. This should never be used to reference another function, hook, class, or method — see @see.*

And:

*@see: Reference to a function/method/class that the function/method relies on.*

So, while generic phpDocumentor allows linking URLs with @see, WordPress core’s own standard distinguishes them semantically — and this PR is aligning core with that documented WordPress standard for consistency.

Otherwise… I guess we might need to update the WordPress PHP Documentation Standards too 😄

[SergeyBiryukov]

In 61568:

Docs: Replace some @see tags with @link for URLs in wp-admin.

Follow-up to [59958].

Props huzaifaalmesbah, shailu25, noruzzaman, westonruter.
See #64224.

[SergeyBiryukov]

In 61572:

Docs: Replace some @see tags with @link for URLs in wp-includes/rest-api/.

Follow-up to [38832], [52275].

Props huzaifaalmesbah, shailu25, noruzzaman, westonruter.
See #64224.

[westonruter]

In 61574:

Docs: Correct type of WP_Theme::$cache_expiration from bool to int.

Follow-up to [20029].

Props marian1, mukesh27.
See #20103, #64224.
Fixes #64583.

Trac Ticket: https://core.trac.wordpress.org/ticket/64224

Why this change?

This change adds missing @global documentation tags to functions in
src/wp-includes/meta.php
src/wp-includes/deprecated.php

This aligns the codebase with the WordPress PHP Documentation Standards, ensuring that global variables used within functions are properly documented for better static analysis and code clarity.

Files Changed:
src/wp-includes/meta.php
src/wp-includes/deprecated.php

[SergeyBiryukov]

In 61584:

Docs: Document the $wp_meta_keys global in meta registration functions.

Follow-up to [37924].

Props noruzzaman, mukesh27.
See #64224.

[SergeyBiryukov]

In 61589:

Docs: Document some globals in WP_UnitTestCase_Base class methods.

Follow-up to [26005], [27183], [29251], [30276], [35136], [35258], [38678], [39626], [44633], [56212].

Props noruzzaman, mukesh27, SergeyBiryukov.
See #64224.

This PR adds missing descriptions to @return tags in various files within src/wp-admin/includes and src/wp-includes to ensure compliance with WordPress Coding Standards.

Trac Ticket: https://core.trac.wordpress.org/ticket/64224

Why this change?

This change adds missing @global documentation tags to functions in
src/wp-admin/includes/misc.php
src/wp-admin/includes/template.php
src/wp-admin/install.php

This aligns the codebase with the WordPress PHP Documentation Standards, ensuring that global variables used within functions are properly documented for better static analysis and code clarity.

Files Changed:
src/wp-admin/includes/misc.php
src/wp-admin/includes/template.php
src/wp-admin/install.php

@noruzzamans Looks good. i have suggest minor changes.

Please exclude the bundled theme changes, as they are already being tracked in a separate ticket. #58715

This all not blocker but nice to have. Thanks @huzaifaalmesbah for the PR!

@westonruter for you if you want to commit or have any suggestions.

In keeping also with Core-64238, in 7a409a2 I've had Gemini help me flesh out the return types to be more specific than just simply array.

@noruzzamans Please exclude the bundled theme changes, as they are already being tracked in a separate ticket. #58715

@shail-mehta @sabernhardt Thanks. I have reverted the bundled theme changes. Actually, I didn’t know it had a separate ticket.

[SergeyBiryukov]

In 61591:

Docs: Document the globals in wp_print_plugin_file_tree().

Follow-up to [41851].

Props noruzzaman, huzaifaalmesbah, shailu25, sabernhardt.
See #64224.

[SergeyBiryukov]

In 61592:

Docs: Add missing @global descriptions in wp-admin/includes/schema.php.

Follow-up to [32643], [45734].

Props noruzzaman, huzaifaalmesbah, shailu25, sabernhardt.
See #64224.

[westonruter]

In 61594:

Docs: Add descriptions and improved typing to @return tags in various admin and includes files.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/10863

Props huzaifaalmesbah, westonruter, noruzzaman, mukesh27.
See #64224.

Committed in r61594 (45a4e0f)

[SergeyBiryukov]

In 61595:

Docs: Document the $wpdb global in wp_register_core_abilities().

Follow-up to [61063], [61069].

Props noruzzaman, huzaifaalmesbah, shailu25, sabernhardt.
See #64224.

@noruzzamans Could you please resolve conflicts?

It looks like this PR may already have been committed:

• Changeset 61584
• Changeset 61589

@shail-mehta @westonruter @mukeshpanchal27 @huzaifaalmesbah Thanks for review. I have updated all changes. if need any changes please let me know. Thanks

[SergeyBiryukov]

In 61599:

Docs: Remove @return void from Abilities API DocBlocks.

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

Follow-up to [55725], [56943], [61063], [61069].

See #64224.

Let’s update the PR title and description, as they’re outdated now.

@mukeshpanchal27 Thanks. I have updated the title and description based on your suggestion.

[westonruter]

In 61604:

Docs: Improve @global annotations in abstract-testcase.php

Developed in ​https://github.com/WordPress/wordpress-develop/pull/10841

Follow-up to [61589], [61584].

Props noruzzaman, mukesh27, westonruter, shailu25, huzaifaalmesbah.
See #64224.

Committed in r61604 (4cad33a)

Replace Closure call syntax ( $fn )( ...$args ) with equivalent call_user_func( $fn, ...$args ).

This prevents an issue with the ​WordPress documentation parser:

Parse Error: Syntax error, unexpected '('

Follow-up to [58304].
See #61348.

[jonsurrell]

In 61624:

HTML API: Use more universal syntax to call Closure variable.

Replace ( $fn )( ...$args ) syntax with equivalent call_user_func( $fn, ...$args ) to prevent an issue with the WordPress documentation parser. The parser would fail when encountering this syntax, preventing documentation generation.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/10907.

Follow-up to [58304].

Props dmsnell, jonsurrell.
See #64224, #61348.

Merged in r61624.

[westonruter]

In 61638:

Docs: Add missing @global variable descriptions.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/10864

Follow-up to [61604], [61592].

Props noruzzaman, huzaifaalmesbah, shailu25, sabernhardt, westonruter.
See #64224.

Committed in r61638 (039e100)

Trac Ticket: https://core.trac.wordpress.org/ticket/64224

Why this change?

This change adds missing @global documentation tags.

This aligns the codebase with the WordPress PHP Documentation Standards, ensuring that global variables used within functions are properly documented for better static analysis and code clarity.

Note: There's no real need to merge trunk back into a branch unless it's likely there will be a merge conflict or a breakage. The committer will ultimately ensure the latest from trunk is merged at the time of commit to SVN.

Some function docblocks still have scope improvements on class-wp-links-list-table.php: ​L79 ​L86 ​L145

Although these are not related to globals or parameters, they are missing proper summaries and return documentation. Could you please review and update these as well?

Thanks @huzaifaalmesbah. I have updated and improved the missing docs.

Note: There's no real need to merge trunk back into a branch unless it's likely there will be a merge conflict or a breakage. The committer will ultimately ensure the latest from trunk is merged at the time of commit to SVN.

Thanks. I have resolved all issues.

[westonruter]

In 61657:

Docs: Add missing @global descriptions and refine parameter documentations in wp-admin/includes classes.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/10931

Follow-up to [61638].

Props noruzzaman, huzaifaalmesbah, westonruter.
See #64224.

Committed in r61657 (1a7da55fd14f22d9d5028ff3a3e92807e6c63eea).

Trac Ticket: https://core.trac.wordpress.org/ticket/64224

Why this change?

This change adds missing @global documentation tags.

This aligns the codebase with the WordPress PHP Documentation Standards, ensuring that global variables used within functions are properly documented for better static analysis and code clarity.

[SergeyBiryukov]

In 61683:

Docs: Add missing descriptions for WP_Media_List_Table methods.

Follow-up to [11749], [15491], [31162], [32654], [61594].

Props noruzzaman.
See #64224.

[SergeyBiryukov]

In 61698:

Docs: Add missing descriptions for WP_MS_Sites_List_Table methods.

Follow-up to [15491], [16992].

Props noruzzaman, huzaifaalmesbah.
See #64224.

This patch improves the PHPDoc docblocks in WP_List_Table and WP_Plugins_List_Table for accuracy, completeness, and consistency with WordPress core documentation standards.

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

[westonruter]

In 61717:

Docs: Supply missing documentation in WP_MS_Themes_List_Table.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/10963

Props noruzzaman, westonruter, huzaifaalmesbah.
See #64224.

Committed in r61717 (dc64903)

[westonruter]

In 61718:

Docs: Improve accuracy of @return type and description for get_post_custom().

Developed in ​https://github.com/WordPress/wordpress-develop/pull/10996

Follow-up to [52795].

Props ravikhadka, westonruter, swissspidy, roytanck.
See #64224, #55249.
Fixes #60646.

Trac ticket: Core-64224

Resolves: ​https://github.com/WordPress/Documentation-Issue-Tracker/issues/1849

This was previosly listed as defaulting to false when in fact it defaults to true.

As this is a documentation-only change it should include no code or functionality changes.

Trac Ticket: https://core.trac.wordpress.org/ticket/64224

Why this change?

This aligns the codebase with the WordPress PHP Documentation Standards, ensuring that global variables used within functions are properly documented for better static analysis and code clarity.

Missing Tags: Added missing @global, @param, and @return descriptions.
Method Summaries: Added summaries for several methods in both list table classes that were previously undocumented.
Property Docs: Added DocBlocks for class properties ($order, $orderby, etc.).

[audrasjb]

In 61723:

Docs: Add missing space and remove duplicate operator values in WP_Date_Query docblocks.

Props truptikanzariya.
Fixes #64713.
See #64224.

[audrasjb]

In 61724:

Docs: Indentation fix after [61723].

See #64713, #64224.

just to update those tagging on to this ticket now; it would have been merged yesterday except for the flakey end-to-end tests which are failing. as soon as those pass and I’m around to do it, I will merge.

Changed the parameter name in the docblock from $_request to $request in the get_items_permissions_check method of WP_REST_Icons_Controller to match the actual parameter name.

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

[dmsnell]

In 61735:

Docs: Fix backwards default value for wp_list_users()::exclude_admin.

This was previosly listed as defaulting to false when in fact it defaults to true.

Developed in: ​https://github.com/WordPress/wordpress-develop/pull/11022
Discussed in: https://core.trac.wordpress.org/ticket/64224
Reported in: ​https://github.com/WordPress/Documentation-Issue-Tracker/issues/1849

Props dmsnell, noruzzaman, vHeemstra, westonruter.
See #64224.

Merged in [61735]
​https://github.com/wordpress/wordpress-develop/commit/792c4ac7a0f81e2a25953adf9ddef5916195386a

[SergeyBiryukov]

In 61739:

Docs: Correct parameter variable name in WP_REST_Icons_Controller.

Follow-up to [61674].

Props Soean, apermo.
See #64224.

Thanks for the PR! Merged in r61739.

WordPress 6.7 introduced many methods to the HTML API. They were intitially stub implementations, but later were fully implemented. The "stub implementation" since annotations incorrectly remained in many cases.

See https://core.trac.wordpress.org/browser/tags/6.7/src/wp-includes/html-api/class-wp-html-processor.php where the "stub implementation" annotations are present on fully implemented methods.

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

The HTML API relies on many private and internal methods and classes. All of theme appear in the public documentation. This introduces a lot of noise into the documentation that's irrelevant for anyone not working directly on the HTML API itself.

By adding ignore annotations to most of the internal and private methods and classes, the documentation will be much cleaner and more relevant.

​See the HTML processor class methods page for example. None of these internal methods should be of interest to folks _using_ the HTML API:

<kbd></kbd>

I have kept a few "internal" things documented, like the WP_HTML_Text_Replacement and WP_HTML_Span which are often useful for subclasses working with bookmarks and replacements.

​https://github.com/WordPress/wordpress-develop/blob/33ebdd7e1135590e4d1a0beec6a5ecfb7fa2cf6f/src/wp-includes/html-api/class-wp-html-text-replacement.php#L16-L22
​https://github.com/WordPress/wordpress-develop/blob/33ebdd7e1135590e4d1a0beec6a5ecfb7fa2cf6f/src/wp-includes/html-api/class-wp-html-span.php#L19-L25

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

Trac Ticket: https://core.trac.wordpress.org/ticket/64224

Why this change?

This aligns the codebase with the WordPress PHP Documentation Standards, ensuring that global variables used within functions are properly documented for better static analysis and code clarity.

Missing Tags: Added missing @global, @param, and @return descriptions.
Method Summaries: Added summaries for several methods in both list table classes that were previously undocumented.
Property Docs: Added DocBlocks for class properties ($order, $orderby, etc.).

Does the docs generator not ignore @access private symbols?

No, it doesn't seem to. @ignore is used to hide things from public documentation.

@access private seems to add ​a notice to methods, but ​not to classes. I've created ​https://github.com/WordPress/phpdoc-parser/issues/255 for this.

​(I also noticed that private methods may include confusing recommendations from `@see` annotations).

[jonsurrell]

In 61792:

HTML API: Remove incorrect "stub implementation" since annotations.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/11076.

Props jonsurrell, westonruter.
See #64224.

Merged in r61792.

[jonsurrell]

In 61793:

HTML API: Exclude internal classes and methods from documentation.

Add @ignore annotations to internal HTML API methods and classes to exclude them from generated documentation. The HTML API relies heavily on internal methods and classes and they create a lot of noise in documentation.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/11078.

Props jonsurrell, westonruter.
See #64224.

Merged in r61793.

## Summary

The rest_revision_query filter in WP_REST_Revisions_Controller::get_items() carried a cross-reference comment claiming it was documented in the posts controller:

/** This filter is documented in wp-includes/rest-api/endpoints/class-wp-rest-posts-controller.php */
$args = apply_filters( 'rest_revision_query', $args, $request );

That cross-reference is incorrect. The posts controller documents rest_{$this->post_type}_query — a dynamic hook that fires only for post types managed by WP_REST_Posts_Controller. WP_REST_Revisions_Controller extends WP_REST_Controller directly (not the posts controller), so the dynamic hook never fires for revisions. rest_revision_query is a standalone hook and has never had its own PHPDoc block.

## Changes

• Replace the broken cross-reference comment with a proper @since 4.7.0 PHPDoc block for rest_revision_query
• Add @see WP_REST_Posts_Controller::get_items() to the get_items() method docblock to surface the parallel relationship between the two controllers, following the same {@see} pattern used in comment.php and post.php for related hooks

## Use of AI Tools

Research (architectural investigation, prior-art search across core) and code were produced by Claude Code (claude-sonnet-4-6). The contributor reviewed the findings, steered the documentation approach, and approved the final implementation.

## Summary

Fixes 8 broken "This filter/action is documented in …" cross-reference comments where the referenced file path contains a typo or incorrect prefix:

• wp-includes/widget.php → wp-includes/widgets.php (missing 's') — 3 xrefs
• edit-form-blocks.php → wp-admin/edit-form-blocks.php (missing prefix) — 1 xref
• wp-admin/post.php → wp-admin/includes/post.php (missing includes/) — 1 xref
• src/wp-admin/includes/file.php → wp-admin/includes/file.php (spurious src/) — 2 xrefs
• wp-admin/includes/media.php → wp-includes/media.php (wrong path) — 1 xref

Also corrects two hook type labels (filter → action for wp_creating_autosave, action → filter for unzip_file).

For detailed investigation notes, see: ​https://github.com/apermo/wordpress-develop/milestone/2

## Use of AI Tools

Research (cross-reference audit using custom PHPStan rules and PHP scripts) and code were produced by Claude Code (claude-sonnet-4-6). The contributor reviewed the findings, verified each fix, and approved the final implementation.

## Summary

Fixes 17 broken "This filter/action is documented in …" cross-reference comments where the hook was moved to a different file but the cross-reference was not updated:

• wp-admin/widgets.php → wp-admin/widgets-form.php (sidebar_admin_setup, delete_widget) — 5 xrefs
• wp-includes/query.php → wp-includes/class-wp-query.php (comment_feed_* filters) — 5 xrefs
• wp-includes/wp-diff.php → wp-includes/class-wp-text-diff-renderer-table.php (process_text_diff_html) — 2 xrefs
• wp-includes/comment-template.php → wp-includes/comment.php (comment_flood_message) — 1 xref
• wp-includes/ms-settings.php → wp-includes/ms-load.php (ms_network_not_found) — 1 xref
• wp-includes/ms-blogs.php → wp-includes/ms-site.php (delete_blog, deleted_blog) — 2 xrefs
• wp-includes/class-wp-image-editor-imagick.php → wp-includes/class-wp-image-editor-gd.php (image_save_progressive) — 3 xrefs (core only; 3 additional in bundled Gutenberg)
• wp-includes/class-wp-image-editor.php → wp-includes/media.php (image_editor_output_format) — 1 xref

For detailed investigation notes, see: ​https://github.com/apermo/wordpress-develop/milestone/2

## Use of AI Tools

Research (cross-reference audit using custom PHPStan rules and PHP scripts) and code were produced by Claude Code (claude-sonnet-4-6). The contributor reviewed the findings, verified each fix, and approved the final implementation.

## Summary

Fixes 3 cases where hooks are registered with the wrong function — add_action() used on a filter or add_filter() used on an action. Functionally equivalent (since add_action() calls add_filter() internally), but semantically incorrect.

### add_filter() → add_action() (hook is fired via do_action()):

• admin_print_styles in wp-admin/includes/admin-filters.php
• login_head in wp-includes/default-filters.php

### add_action() → add_filter() (hook is fired via apply_filters()):

• use_block_editor_for_post_type in wp-admin/includes/admin-filters.php

A 4th mismatch (get_block_type_variations using add_action() on a filter) originates in the Gutenberg repo and is tracked separately: ​https://github.com/WordPress/gutenberg/issues/76296

For detailed investigation notes, see: ​https://github.com/apermo/wordpress-develop/milestone/4

## Use of AI Tools

Research (systematic cross-referencing of all add_action/add_filter registrations against their do_action/apply_filters call sites) and code were produced by Claude Code (claude-sonnet-4-6). The contributor reviewed the findings, verified each fix, and approved the final implementation.

## Summary

Adds 11 missing "This filter/action is documented in …" cross-reference comments for hook calls that have a canonical PHPDoc block elsewhere but were missing the xref:

• the_title (×4 in wp-includes/deprecated.php) → canonical PHPDoc in wp-includes/post-template.php
• link_category (×1 in wp-includes/deprecated.php) → canonical PHPDoc in wp-includes/bookmark-template.php
• enqueue_block_assets (×1 in wp-includes/block-editor.php) → canonical PHPDoc in wp-includes/script-loader.php
• Legacy load-*.php actions (×5 in wp-admin/admin.php) → canonical PHPDoc for load-{$pagenow} in the same file

For detailed investigation notes, see: ​https://github.com/apermo/wordpress-develop/milestone/5

## Use of AI Tools

Research (cross-reference audit across all hook call sites in core) and code were produced by Claude Code (claude-sonnet-4-6). The contributor reviewed the findings, verified each fix, and approved the final implementation.

[SergeyBiryukov]

In 61878:

Docs: Correct duplicate hook references in various files.

This commit adjusts cross-reference comments where the hook was moved to a different file but the cross-reference was not updated.

Props apermo, mukesh27.
See #64224.

Thanks for the PR! Merged in r61878.

[SergeyBiryukov]

In 61946:

Docs: Correct path typos in duplicate hook references.

This adjusts cross-reference comments where the referenced file path contains a typo or an incorrect prefix.

Follow-up to [61878].

Props apermo, mukesh27.
See #64224.

Thanks for the PR! Merged in r61946.

[westonruter]

In 61994:

Docs: Add missing hook cross-reference docblock comments.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/11205

Props apermo, mukesh27.
See #64224.

Committed in r61994 (78ec1ff)

[johnjamesjacoby]

In 61995:

Docs: Correct lone @param null usages around some $deprecated vars.

Update incorrect uses of null as a single parameter type to be mixed instead, largely targeting $deprecated variable names.

Pipe | a few nulls with other valid types where appropriate.

Add a missing empty new-line between the _deprecated_file() and _deprecated_argument() functions.

See #64224.

[SergeyBiryukov]

In 61998:

Docs: Explicitly document the rest_revision_query filter.

The rest_revision_query filter in WP_REST_Revisions_Controller::get_items() carried a cross-reference comment claiming it was documented in the posts controller. This was incorrect, as the posts controller documents rest_{$this->post_type}_query — a dynamic hook that fires only for post types managed by WP_REST_Posts_Controller.

WP_REST_Revisions_Controller extends WP_REST_Controller directly (not the posts controller), so the dynamic hook never fires for revisions. rest_revision_query is a standalone hook and has never had its own PHPDoc block.

Follow-up to [43584].

Props apermo, mukesh27, SergeyBiryukov.
See #64224.

Thanks for the PR! Merged in r61998.

For reference, it appears that the correct @since version here is 5.0.0 rather than 4.7.0, see r43584.

[westonruter]

In 62041:

Docs: Indicate that get_posts() can take a query string in addition to an array of query vars.

A string is supported by virtue of wp_parse_args() being used on the supplied arguments. While a string is not currently passed to get_posts() in core, a significant number of plugins are doing so. So in addition to documenting actual ecosystem usage, this also adds a test to ensure that supplying a query string continues to be supported in the future.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/11179

Follow-up to r11528.

Props rodrigosprimo, westonruter, shailu25, mukesh27.
See #64224, #10047.
Fixes #64813.

[desrosj]

Opened #64896 for the 7.1 release cycle. With 7.0 RC1 due out today, going to close this out. This can be reopened or referenced if there are more changes needed related to this during 7.0.