Docblock improvements for 7.1

[desrosj]

Previously:

• #64224 (7.0)
• #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)

[noruzzaman]

I noticed that both #64717 and #64896 are tracking the same Docblock improvements for WordPress 7.1.

To avoid duplicate tracking, I think it would be better to keep one ticket as the main reference and close the other as a duplicate.

[johnbillion]

In 62430:

Docs: Remove duplicate documentation for the rest_block_hooks_post_types hook.

See #62715, #64896

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

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.).

[jonsurrell]

#64717 was marked as a duplicate.

Apply many documentation fixes across the HTML API. Changes include a wide range of issues from typos, mistakes, punctuation, grammar, and simple inaccuracies.

AI discovered and implemented corrections. All changes have been reviewed by me.

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

## Use of AI Tools

AI assistance: Yes
Tool(s): Claude (primary). Codex and GitHub Copilot for review.
Used for: Detecting and applying corrections. Review.

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/64896
https://core.trac.wordpress.org/ticket/64224

[westonruter]

In 62491:

Docs: Improve WP_List_Table and WP_Plugins_List_Table docblocks.

Improve the PHPDoc docblocks in WP_List_Table and WP_Plugins_List_Table for accuracy, completeness, and consistency with WordPress core documentation standards. Adds missing @since tags and corrects several existing versions, adds summary descriptions to all previously bare method and property docblocks, and refines type annotations with precise generic array types.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/10989.
Follow-up to r30679, r31127, r32642, r32654.

Props huzaifaalmesbah, westonruter, noruzzaman.
See #64896.

Committed in r62491 (46f3c09)

[jonsurrell]

In 62507:

HTML API: Correct and improve documentation issues.

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

Props jonsurrell, westonruter, dmsnell.
See #64896.

Merged in r62507.

Updates some language in the documentation from r62507 to use clear technical language.

"Dangerous characters" is an unclear term, while HTML syntax characters is clear and precise. This was intended to be updated before landing ​https://github.com/WordPress/wordpress-develop/pull/12043 but was overlooked.

Follow-up to r62507.

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

## Use of AI Tools

[jonsurrell]

In 62519:

HTML API: Improve comment about HTML syntax characters.

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

Follow-up to [62507].

Props dmsnell.
See #64896.

Committed in r62519.

Trac ticket: #64896

### Why this change?

• Updated Inline Documentation Order According to ​PHP Coding Standards

1. Added @see tag before @param tag in Below files:

• src/wp-includes/author-template.php
• src/wp-includes/customize/class-wp-customize-nav-menu-setting.php

2. Added @global tag after @see tag in Below files:

• src/wp-includes/post.php
• src/wp-includes/taxonomy.php

3. Added @deprecated tag after @since tag in Below file:

• src/wp-includes/interactivity-api/class-wp-interactivity-api.php

## Use of AI Tools

• None

The suggested changes have been applied.

The preferred way for users to iterate through an HTML document with the HTML Processor is via the methods ::next_tag() or ::next_token(). ::step() remains a public method, but is a discouraged interface.

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

[jonsurrell]

In 62594:

HTML API: Discourage public use of the step() method.

The preferred way to iterate with WP_HTML_Processor is via ::next_tag() or ::next_token().

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

Props jonsurrell, dmsnell.
See #64896.

Merged in r62594.

[westonruter]

In 62640:

Docs: Add numeric-string types to DB-backed class properties.

Add @phpstan-var numeric-string annotations to string properties which hold integer database values:

• WP_Comment::$comment_ID
• WP_Comment::$comment_post_ID
• WP_Comment::$comment_karma
• WP_Comment::$comment_parent
• WP_Comment::$user_id
• the eight WP_Site properties backed by integer columns of the wp_blogs table
• the private WP_Network::$blog_id property

Previously the numeric-string nature of such properties was only indicated in the property description:

A numeric string, for compatibility reasons.

Additionally, document the magic WP_Network::$blog_id property, which is exposed via __get() as a numeric string but was missing from the class-level @property tags.

Finally, correct the documented types of three magic properties:

• WP_Site::$post_count is lazy-loaded via get_option(), so it is a numeric string once read back from the database and false when the option is not set (new sites with no published posts); it holds an integer only when served from the options cache in the same request that updated it.
• WP_User::$user_status always holds a numeric string coming raw off the users table row.
• WP_User::$user_level resolves through user metadata as a numeric string (or an empty string when the metadata is absent), holding an integer only after WP_User::update_user_level_from_caps() has assigned one to the instance in the same request.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/12408.
Follow-up to r37657, r37870, r38630, r48941, r62437.

See #44723, #64896, #64898.

[westonruter]

In 62648:

Code Quality: Add conditional return types to post functions.

Annotate the core post retrieval, sanitization, and insertion APIs with PHPStan conditional return types keyed on their mode arguments, so static analysis can resolve the concrete result at each call site:

• get_post(), get_page(), get_page_by_path(), get_children(), and get_post_types() narrow on $output.
• get_posts() and WP_Query::query() narrow on the fields argument.
• get_post_field() and sanitize_post_field() narrow on $field.
• wp_insert_post(), wp_update_post(), and wp_insert_attachment() narrow on $wp_error.

Matching @phpstan-param tags are added where the analyzed return depends on a narrowed input.

Separately, several previously generic or underspecified types are filled in where the precise type is known:

• WP_Post::to_array() is typed array<string, mixed> rather than a bare array.
• WP_Post::$filter is annotated with its recognized context values rather than a bare string.
• WP_Post::filter() is corrected to return WP_Post|false (previously WP_Post), and its missing summary is documented.
• sanitize_post()'s $post parameter is narrowed from object to stdClass|WP_Post.

Because these functions were previously typed as returning mixed or a bare object, the sharper types let analysis see through to hundreds of downstream call sites, for a net reduction of roughly 280 PHPStan errors across the tree.

A few supporting runtime changes make the types hold:

• get_post() now guards against the false that WP_Post::filter( 'raw' ) can return for a since-deleted post.
• WP_Post::get_instance() tightens its cache-hit check.
• post IDs are cast to int where passed on.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/12426.
Follow-up to r61789.

See #64898, #64896.

Follow-up to https://core.trac.wordpress.org/changeset/62332

This adds a WP_Hook_Callback PHPStan type to represent the shape of a callback used internally in WP_Hook and used in return values of array access methods.

Also narrows a few other documented types.

I was looking into the other PHPStan rule level 10 issues in this file, and I found something related to the change you made here. It seems the offsetSet() method is lacking the use of the new type. I tried adding it:

--- a/src/wp-includes/class-wp-hook.php
+++ b/src/wp-includes/class-wp-hook.php
         *
         * @param mixed $offset The offset to assign the value to.
         * @param mixed $value The value to set.
+        *
+        * @phpstan-param array-key|null $offset
+        * @phpstan-param array<string, Hook_Callback> $value
         */
        #[ReturnTypeWillChange]
        public function offsetSet( $offset, $value ) {

But there are two errors remaining here:

​https://github.com/WordPress/wordpress-develop/blob/6e10867dd4ac6d1420aef8d992fad255c3c9e879/src/wp-includes/class-wp-hook.php#L520-L528

At:

​https://github.com/WordPress/wordpress-develop/blob/6e10867dd4ac6d1420aef8d992fad255c3c9e879/src/wp-includes/class-wp-hook.php#L524

phpstan: Property WP_Hook::$callbacks (array<int, array<string, array{function: callable(): mixed, accepted_args: int}>>) does not accept non-empty-array<int|string, array<string, array{function: callable(): mixed, accepted_args: int}>>.

And at:

​https://github.com/WordPress/wordpress-develop/blob/6e10867dd4ac6d1420aef8d992fad255c3c9e879/src/wp-includes/class-wp-hook.php#L527

phpstan: Property WP_Hook::$priorities (list<int>) does not accept non-empty-list<int|string>.

Addressed in 67f3a9b.

This is stacked on #12441 and includes all of its commits. The only new commit here is b0d8b59476, which resolves the remaining PHPStan level 10 errors in WP_Hook on top of the type tightening done in that PR. @johnbillion: feel free to merge this into your branch if you want to fold it in; otherwise I'll rebase onto trunk once your PR lands.

The new commit:

• Adds the Iterator/ArrayAccess generics via @phpstan-implements (already pushed to #12441) and @return void to the methods lacking return values.
• Documents the callback $args arrays as list<mixed> and narrows the $callback params of remove_filter()/has_filter() to callable, matching add_filter().
• Passes 0 instead of false to _wp_filter_build_unique_id() in has_filter(), matching its int $priority param. (The value is unused for the key, so this is behavior-neutral.)
• Restructures the apply_filters() loop to assign the current priority to a local variable before storing it in $current_priority, bailing from the loop in the (impossible) case that current() returns false. This keeps $current_priority honestly typed as array<int, int>; previously, PHPStan saw int|false being stored.

With this, vendor/bin/phpstan analyse src/wp-includes/class-wp-hook.php reports no errors at level 10.

## Use of AI Tools

AI assistance: Yes
Tool(s): Claude Code
Model(s): Claude Fable 5
Used for: Diagnosing the PHPStan level 10 errors and drafting the fixes in the final commit; I reviewed, adjusted, and take responsibility for the changes.

---
This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See ​GitHub Pull Requests for Code Review in the Core Handbook for more details.

🤖 Generated with ​Claude Code

​https://claude.ai/code/session_01Y1qB3ZWwGV2nBtdb9NgcJa

I've followed up with ​https://github.com/WordPress/wordpress-develop/pull/12443 to add ​https://github.com/WordPress/wordpress-develop/pull/12443/changes/b0d8b59476800f371ed7b52016bc8ec0b4d752d8 which fixes the remaining PHPStan level 10 errors in class-wp-hooks.php. If you don't want to include those fixes in your commit here, I can commit it separately.

@noruzzamans This PR has merge conflicts with trunk. Could you please rebase/update the branch and resolve the conflicts?

Thanks @huzaifaalmesbah . I have resolved these conflicts. Please review it and let me know if need any improvement.

The new commit:

• Adds @return void to the methods lacking return values.

As per the ​documentation standards, this should generally be avoided:

Note: @return void should not be used outside the default bundled themes and the PHP compatibility shims included in WordPress Core.

That said, it is quite possible that this point is now outdated and should perhaps be reconsidered.

@SergeyBiryukov:

That said, it is quite possible that this point is now outdated and should perhaps be reconsidered.

I think it is obsolete, yes. PHPStan identifies the lack of a return type as an error. New void-returning functions being introduced in core have been using the native void type hint. That said, we could configure PHPStan to ignore the missing return type, but why? Better to be explicit.

Related: There has been cases of void being used in core already which have been replaced with null in unions via Core-64704.

[westonruter]

In 62704:

Docs: Add never return types to functions that always terminate.

Documents @return never on 30 functions and methods whose every control-flow path ends in exit, die(), wp_die(), or wp_send_json_*(), so static analysis knows the code following a call to them is unreachable. Native never requires PHP 8.1, so these are PHPDoc-only.

Where terminating depends on a parameter, a conditional @phpstan-return describes each case rather than over-widening to the union of both. The seven wp_die() handlers gain the same conditional wp_die() itself already carries. trackback_response() and wp_protect_special_option() never return for the parameter values that die, while redirect_canonical(), check_admin_referer(), check_ajax_referer(), and get_cli_args() narrow their return types accordingly.

The bottom type never was also incorrectly declared in the return type union for get_cli_args(), so it was removed.

Developed as subset of ​https://github.com/WordPress/wordpress-develop/pull/12488.
Follow-up to r62703, r62178, r62177.

Props westonruter, mukesh27.
See #64896, #64898.

[westonruter]

In 62717:

Code Quality: Improve WP_Post type coverage.

Add a Data_Array array-shape type describing every key returned by WP_Post::to_array(), and tighten each WP_Post property to the narrowest type the schema and code guarantee:

• ID and post_parent become non-negative-int.
• comment_count becomes numeric-string, and post_author becomes numeric-string|'' (a user ID, or an empty string for a default post that has not yet been assigned an author).
• The always-populated post_status, comment_status, ping_status, and post_type slugs become non-empty-string, left open rather than enumerated so custom statuses and types remain valid.
• The magic ancestors, post_category, and tags_input accessors become precise lists (list<non-negative-int> and list<non-empty-string>).

The shape stays open because WP_Post permits dynamic properties. Fields that can legitimately be empty, including the datetime fields (which get_default_post_to_edit() may leave empty), stay string, and menu_order stays int since it can be negative.

Correct WP_Post::$filter, which was previously typed without null or the 'sample' context: an unsanitized post has no filter (checked in core via isset() and empty()), and get_sample_permalink() has assigned 'sample' since [8526]. Widen sanitize_post_field()'s $context to accept 'sample' to match, which it already treats as a 'display' context.

Also type get_post_ancestors() as returning list<non-negative-int>, read the post in trackback_url_list() via to_array() while guarding against a missing post, and cast post_author to a string in WP_Customize_Nav_Menu_Item_Setting and inject_ignored_hooked_blocks_metadata_attributes(), which each populate an object before passing it to new WP_Post().

Developed in ​https://github.com/WordPress/wordpress-develop/pull/12491.
Follow-up to r62648, r62694.

See #64898, #64896.

[westonruter]

In 62721:

Docs: Add specific types to WP_Network_Query properties.

Replace the generic array type in the docblocks for the $sql_clauses, $query_vars, $query_var_defaults, and $networks properties with specific types, including an array shape for $sql_clauses and WP_Network[]|int[] for $networks. Additionally, document the $found_networks and $max_num_pages counts as non-negative-int.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/11663.
Follow-up to r37894.

Props baikaresandeep007-1, westonruter.
See #64896.
Fixes #65118.

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

I agree that refraining from using @return void is outdated, but let's handle that separately from these changes.

[westonruter]

In 62752:

General: Allow configuration of speculative loading defaults via env variables and constants.

Introduce two overrides that let a site or hosting provider change the default speculative loading configuration that the auto value resolves to, without having to ship an mu-plugin:

• WP_SPECULATIVE_LOADING_DEFAULT_MODE (prefetch or prerender)
• WP_SPECULATIVE_LOADING_DEFAULT_EAGERNESS (conservative, moderate, or eager).

Each may be supplied as an environment variable, read via getenv(), or as a constant of the same name that takes precedence over it, mirroring how wp_get_environment_type() resolves WP_ENVIRONMENT_TYPE. An unrecognized value falls back to the core default.

These overrides only change what auto resolves to, so an explicit mode or eagerness supplied through the wp_speculation_rules_configuration filter still wins. An eagerness of immediate is rejected because WordPress does not permit it for the document-level rules it generates; accepting it would cause WP_Speculation_Rules::add_rule() to reject the rule and leave the page with no speculation rules at all.

Also relax WP_Speculation_Rules::is_valid_mode() and WP_Speculation_Rules::is_valid_eagerness() to accept mixed, so an arbitrary value from the filter is validated and rejected rather than raising a TypeError.

Fix PHPStan errors in speculative loading functions resulting from insufficient typing.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/12514.
Follow-up to r59837.

Props westonruter, mukesh27, adamsilverstein, swissspidy.
See #64066, #62503, #64896, #64898.
Fixes #65624.

I agree that refraining from using @return void is outdated, but let's handle that separately from these changes.

Reverted in 199b9ce

Trac Ticket:
https://core.trac.wordpress.org/ticket/64896
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

Thanks for the review @westonruter ! Both points are now addressed:

• Merge conflicts have been resolved.
• The @see → @link change has been applied to all WordPress core PHP occurrences. Bundled libraries were excluded.

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

While working on #12680 found this typo issue.

Correct If black to If blank in the inline comment describing the optional RSS widget title handling. Longstanding typo, comment-only, no functional change.

## Use of AI Tools
N/A

[SergeyBiryukov]

In 62849:

Docs: Fix typo in a comment in wp_dashboard_rss_control().

Follow-up to [6705].

Props mukesh27.
See #64896.

Oops, it looks like this PR has already been committed. https://core.trac.wordpress.org/changeset/62849

[westonruter]

In 62893:

Bundled Themes: Fix hook docblocks and filter arguments.

• Add the missing variable name to @param tags that document a type and a description but no name, in Twenty Ten, Twenty Eleven, and Twenty Twenty-One.
• Pass the documented $post argument to the the_permalink filter in Twenty Eleven, Twenty Thirteen, and Twenty Fifteen. The filter gained that parameter in 4.4, but these call sites were never updated, so a callback registered for two arguments received only one.
• Point Twenty Eleven's widget_title reference comment at wp-includes/widgets/class-wp-widget-pages.php, since wp-includes/default-widgets.php no longer exists. Add the reference comments that were missing altogether for the_permalink in Twenty Thirteen and Twenty Fifteen, and for widget_title in Twenty Fourteen.

These issues were surfaced by the PHPStan extensions under development for this ticket, which are committed separately.

Developed as subset of ​https://github.com/WordPress/wordpress-develop/pull/12022.
Follow-up to r25625, r25627, r33843, r35002, r51304, r60077.

See #65376, #64896.

[westonruter]

In 62934:

Docs: Attach three hook doc comments to their filter calls.

Hook documentation is located by adjacency: the docblock must be the last thing before the line containing the apply_filters() or do_action() call, as established in r46088. In three places it was not, so the comment documented nothing.

• In wp-admin/includes/ms.php the reference comment for users_have_additional_content was opened with /* rather than /**, making it an ordinary block comment instead of a docblock.
• In wp-admin/includes/template.php the reference comment for editable_slug sat in the middle of a string concatenation, attached to no statement at all; the filter is now applied on its own line and the result interpolated.
• In wp-includes/abilities-api/class-wp-ability.php the sentinel assignment sat between the wp_pre_execute_ability docblock and the call it documents, so the docblock attached to the assignment; the assignment is hoisted above the docblock.

None of this changes behavior. The filters run with the same arguments, in the same order, and produce the same output.

These comments were surfaced by the PHPStan extensions under development for this ticket, which resolve a hook's documentation the same way the parser behind the developer handbook does, and which are committed separately.

Developed as subset of ​https://github.com/WordPress/wordpress-develop/pull/12022.
Follow-up to r27237, r46088, r62397, r62688.

See #65376, #64896.

[westonruter]

In 62935:

Docs: Correct the type of the image_editor_output_format map.

The $output_format array maps a source mime type to a destination mime type, so its keys are mime type strings. Since r51221 it has been documented as string[] (which typically means an integer-keyed array of strings) expanded by a hash-notation block whose @type string ...$0 is the notation core uses for numerically indexed members. Both halves therefore described a list, and nothing in the documentation conveyed that the key is the source mime type, which is the entire point of the array.

Replace both with array<string, string>, which states the key and value types directly and needs no nested block. The @return of wp_get_image_editor_output_format() gets the same correction, having inherited string[] when r58849 moved the canonical docblock into wp-includes/media.php.

This mismatch was surfaced by the PHPStan extensions under development for this ticket, which read hook docblocks in order to type the return of apply_filters(), and which are committed separately.

Developed as subset of ​https://github.com/WordPress/wordpress-develop/pull/12022.
Follow-up to r50943, r51221, r58849.

See #65376, #64896.

Merged Branch with Latest Trunk.

WP_Duotone::is_preset() carries two @param tags for the same variable, giving contradictory types, and documents no return value at all:

* @param string $duotone_attr The duotone attribute from a block.
 * @param string|string[] $duotone_attr The duotone attribute from a block.
 */
private static function is_preset( $duotone_attr ) {

In [61603] the type was widened from string to string|string[], but the new tag replaced the @return line rather than the old @param:

-        * @return bool True if the duotone preset present and valid.
+        * @param string|string[] $duotone_attr The duotone attribute from a block.

So the method lost its return documentation and kept a stale parameter type in the same edit.

## Fix

Drop the stale @param and restore the @return. The wording is the one [61603] removed, so nothing here is invented. Two independent references confirm it:

• WP_Duotone::get_slug_from_attribute(), immediately above, was updated by that same changeset and got it right: @param string|string[] and a @return.
• The Gutenberg counterpart, lib/class-wp-duotone-gutenberg.php, still reads @param string|string[] $duotone_attr and @return bool True if the duotone preset present and valid.

string|string[] is the correct type. The method guards with ! is_string( $duotone_attr ) and returns false, which is exactly the array case [61603] was written to handle.

No functional change. phpcs passes on the file.

## Use of AI Tools

AI assistance: Yes
Tool(s): Claude Code
Model(s): Claude Opus 5
Used for: Scanning src/ for docblock and signature disagreements, which is how this was found, and drafting this description. I confirmed the cause in the changeset history, checked the wording against the sibling method and the Gutenberg copy, ran phpcs, and I take responsibility for the change.

Five functions in Twenty Nineteen and Twenty Twelve take arguments but have no @param tag at all, just a one line description.

Twenty Nineteen (inc/template-tags.php)

• twentynineteen_get_user_avatar_markup( $id_or_email = null )
• twentynineteen_discussion_avatars_list( $comment_authors )
• twentynineteen_comment_form( $order )

Twenty Twelve (functions.php)

• twentytwelve_page_menu_args( $args )
• twentytwelve_content_nav( $html_id )

The Twenty Twelve file documents parameters throughout, so those two stand out as gaps rather than a house style.

## Notes on the types

They come from the call sites, not from guesswork.

twentynineteen_comment_form() is documented as bool|string, because comments.php calls it three times, with 'desc', 'asc', and true. The body reads if ( true === $order || strtolower( $order ) === strtolower( get_option( 'comment_order', 'asc' ) ) ), so true forces display while a string only displays when it matches the option. The description says that rather than just listing the types.

twentynineteen_discussion_avatars_list() receives $discussion->authors, built in twentynineteen_get_discussion_data() as ( (int) $comment->user_id > 0 ) ? (int) $comment->user_id : $comment->comment_author_email, so entries are a user ID or an email address where there is no account.

twentynineteen_get_user_avatar_markup() passes its argument straight to get_avatar(), so it takes that function's wording for the accepted types. It also returns markup, so it gains a @return.

twentytwelve_page_menu_args() is a wp_page_menu_args filter callback and returns the array, so it gains a @return as well.

## What is deliberately not changed

No @since tags are added. The Twenty Nineteen file does not use them on functions, and adding them would mean guessing at versions. The two Twenty Twelve functions already have theirs.

No functional change. phpcs passes on both files.

## Use of AI Tools

AI assistance: Yes
Tool(s): Claude Code
Model(s): Claude Opus 5
Used for: Scanning src/ for functions whose docblocks omit their parameters, which is how these were found, and drafting this description. I read each call site to confirm the types, ran phpcs, and I take responsibility for the change.

This was mistaken remove the @return and added duplicate in param https://core.trac.wordpress.org/ticket/64612 / [61603]

[wildworks]

In 62971:

Docs: Restore the @return tag for WP_Duotone::is_preset().

Removes a duplicate @param tag carrying an outdated type and restores the description of the returned value.

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

Follow-up to [61603].

Props bejignesh, mukesh27, wildworks.
See #64896.

Commited: https://core.trac.wordpress.org/changeset/62971

@t-hamano this can be merged as well.

Three core-owned methods are missing a @param tag.

WP_HTTP_IXR_Client::query()

The docblock already records that the ...$args parameter was formalized in 5.5.0 by adding it to the signature, but the parameter itself was never documented. WP_Dependency::__construct() carries the same @since wording and does document it as @param mixed ...$args Dependency information., so this brings the two back in line.

The description matches what the method does with the value: array_shift( $args ) takes the method name, and the remainder are the arguments passed to it.

WP_REST_Font_Collections_Controller::get_items_permissions_check()

Has @since and @return but no @param for $request.

WP_REST_Font_Families_Controller::get_endpoint_args_for_item_schema()

Has @since and @return but no @param for $method.

### Testing

• --group xmlrpc passes, 318 tests.
• The font controller REST tests pass, 143 tests.
• phpcs clean on all three files.
• php -l clean on all three files.

Documentation only, no behaviour change.

## Use of AI Tools

AI assistance: Yes
Tool(s): Claude Code
Model(s): Claude Opus 5
Used for: Drafting the tags and this description. I confirmed each gap against the current file, checked the variadic wording against how core documents the same parameter on WP_Dependency::__construct(), verified the ...$args description against the method body, confirmed no existing ticket or pull request already covers these three, ran the xmlrpc and font REST tests plus phpcs, and I take responsibility for the result.

## Description

remove_filter( $hook_name, $callback, $priority = 10 ) and remove_action( $hook_name, $callback, $priority = 10 ) take three parameters. A number of places in the PHPUnit test suite pass a fourth one, copied over from the matching add_filter()/add_action() call:

add_filter( 'domain_exists', array( $this, 'domain_exists_cb' ), 10, 4 );
$exists = domain_exists( 'foo', 'bar' );
remove_filter( 'domain_exists', array( $this, 'domain_exists_cb' ), 10, 4 );

The fourth argument is silently ignored by PHP, but it is misleading: it suggests $accepted_args is part of the callback identity used to locate and unhook the callback, which it is not. Only the hook name, the callback and the priority are relevant.

This removes the superfluous argument throughout the test suite. Where the priority was the default 10, the now-redundant priority argument is dropped as well:

remove_filter( 'domain_exists', array( $this, 'domain_exists_cb' ) );

Non-default priorities are kept, since remove_filter() only finds a callback under the exact priority it was registered with:

remove_filter( 'pre_do_shortcode_tag', array( $this, 'filter_pre_do_shortcode_tag_attr' ), 12 );

No occurrences remain in src/, so this is a test-only change with no behavioural difference.

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

Feedback responded and it's all good now

A fix to the docblock annotation order to move @param below @global.

Follow up to ​https://github.com/WordPress/wordpress-develop/commit/5bf5b160c6c340e8cc29bf32ed254bc36990d1ef / r63065

This appears in all the branches it was backported to but I think it would be fine to commit this to trunk and the 7.0 branch. 7.1 too if this is not approved prior to branching.

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

## Use of AI Tools

Nope.

Thanks @mukeshpanchal27, as WordPress 7.1 hasn't been branched, I'll need another committer to approve this prior to commit.

This was included in all the branches from the security fix but I think we can get away backporting to 7.0 upward as that will cover the currently supported release branch.

[peterwilsoncc]

In 63173:

Docs: Reorder docblock annotations for send_confirmation_on_profile_email().

Moves the @param annotation below @global per the documentation standards.

Props peterwilsoncc, mukesh27.
See #64896.

Merged in

r63173 / ​https://github.com/WordPress/wordpress-develop/commit/2b2b6a918784a67bb19c6e166fea0a683edba474

[peterwilsoncc]

I'd like to backport r63173 to the 7.1 branch and possibly the 7.0 branch in case it gets another minor release. Could I get an approval from another committer to do so (please be specific about whether it's for one or both branches)?

[joedolson]

Approving for backport to 7.1.

[johnbillion]

Yep approved for backport to 7.1. No need to go to 7.0.

[peterwilsoncc]

In 63189:

Docs: Reorder docblock annotations for send_confirmation_on_profile_email().

Moves the @param annotation below @global per the documentation standards.

Reviewed by joedolson, johnbillion.
Merges r63173 to the 7.1 branch.

Props peterwilsoncc, mukesh27.
See #64896.

[desrosj]

With RC3 due out today, I am going to close this out. That said, documentation changes are generally allowed at any point during the release cycle if they are necessary for the upcoming release. So this can be reopened if anything else is found that must be addressed prior to 7.1's final release.

I've opened #65860 for the 7.2 release cycle.

See ​https://github.com/WordPress/wporg-developer/pull/567 and ​https://github.com/WordPress/wporg-developer/pull/567.

​This was discussed on the July 21 2026 dev chat and mentioned in a few relevant Slack channels (​`#core` and ​`#docs`) and reception was positive.

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

## Use of AI Tools

None

[zieladam]

In 63293:

HTML API: Make class_list() examples interactive.

Converts the WP_HTML_Processor::class_list() and WP_HTML_Tag_Processor::class_list() examples to runnable WordPress Playground snippets. Corrects the encoded closing angle bracket so the expected output matches the parsed class name.

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

Props jonsurrell.
See #64896.

[jonsurrell]

Are folks open to backporting r63293 to 7.1? It's a docs-only change. Reopening to consider the backport.

The reason it would be nice to include in 7.1 is so that the docs have a live example of the runnable code snippets. ​See the linked PR for the demo.

Merged in r63293.

[zieladam]

+1 from me, I would love that to happen!

[wildworks]

Reviewed r63293, approved for backport to the 7.1 branch.

[wildworks]

In 63302:

HTML API: Make class_list() examples interactive.

Converts the WP_HTML_Processor::class_list() and WP_HTML_Tag_Processor::class_list() examples to runnable WordPress Playground snippets. Corrects the encoded closing angle bracket so the expected output matches the parsed class name.

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

Reviewed by wildworks.
Merges [63293] to the 7.1 branch.

Props jonsurrell.
See #64896.