Docblock improvements for 7.2

[desrosj]

Previously:

• #64896 (7.1)
• #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)

Trac ticket: #65860

### Why this change?

• Updated Inline Documentation Order According to ​PHP Documentation 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

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.

Originally opened against #64896, which was closed when 7.1 reached RC3
without this being committed. Moved to the 7.2 docblock ticket.

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

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.

Originally opened against #64896, which was closed when 7.1 reached RC3
without this being committed. Moved to the 7.2 docblock ticket.

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

[bejignesh]

Both of the above came from #64896 and were not committed before it was closed for 7.1, so I have repointed them here. Both still apply cleanly to trunk, and ​PR 12823 was reviewed and approved by ​@soean.

[SergeyBiryukov]

In 63320:

Docs: Remove a blank line between @param and @return in core docblocks.

The ​PHP inline documentation standards place @return immediately after the last @param tag, with no blank line between them:

/**
 * Summary.
 *
 * @since x.x.x
 *
 * @param string $var Description.
 * @return string Description.
 */

This corrects 44 docblocks across 33 files in src/wp-includes that used a line break between the two tags.

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

Props mukesh27, dhruvang21.
See #65818, #65860.

Docs-only follow-up to r62595 (#12319), which rolled back a change to the parse_next_attribute() return docs so it wouldn't hold up the fix. See the review discussion: ​https://github.com/WordPress/wordpress-develop/pull/12319#discussion_r3494789615

Two things were in tension there:

• The return value should be framed positively — "whether an attribute was found" — not as a continuation flag. A true means one was found, not that more follow; a false means none was found, whether because the document ended or some other stop condition was reached.
• The existing doc was confusing in practice: it returns true on end tags even though end tags don't have attributes, and "before the end of the document" is not the only reason it returns false (reaching > is the common one).

This keeps the positive framing and resolves the confusion by making the implicit parts explicit:

• States up front that attribute syntax is parsed on both start and end tags, and that on end tags the attribute is consumed and discarded rather than recorded, but still reported as found.
• Explains why callers loop on it (finding one means another may follow) while being clear that true doesn't promise more.
• Names the concrete false conditions: end of tag (> or />) or end of document.
• Lists the side effects (cursor advance, attribute recording, self-closing flag, STATE_INCOMPLETE_INPUT).
• Adds an inline comment at the is_closing_tag early return, which is the line that prompted the original question.

No behavior change. php -l and phpcs pass; tests/phpunit/tests/html-api/wpHtmlTagProcessor.php passes (560 tests).

Follow-up to r62595 (see #65372).

## Use of AI Tools

AI assistance: Yes
Tool(s): Claude Code
Model(s): Claude Fable 5
Used for: Drafting the docblock and inline comment text from the linked review discussion; reviewed and edited by me.

[SergeyBiryukov]

In 63333:

Docs: Remove a blank line between @param and @return in test docblocks.

The ​PHP inline documentation standards place @return immediately after the last @param tag, with no blank line between them:

/**
 * Summary.
 *
 * @param string $var Description.
 * @return string Description.
 */

This corrects 65 docblocks across 29 files in the PHPUnit test suite.

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

Follow-up to [63320].

Props mukesh27.
See #65818, #65860.

@mukeshpanchal27 Any chance you can sign this off?

@mukeshpanchal27 Any chance you can sign this off?

This property was introduced in 6.5 but wasn't added to the WP_Block_Type docs.

Refs:

• ​https://github.com/WordPress/wordpress-develop/blob/95639420293b22905266a0dd59cf5427756db9d7/src/wp-includes/class-wp-block-type.php#L229-L235
• ​https://github.com/WordPress/wordpress-develop/blob/95639420293b22905266a0dd59cf5427756db9d7/src/wp-includes/rest-api/endpoints/class-wp-rest-block-types-controller.php#L248

Trac ticket: Core-65860

[audrasjb]

In 63339:

Docs: Remove an extra space in the docblock of wp_ajax_nopriv_heartbeat().

Props harishtewari.
Fixes #65938.
See #65860.

Two HTML API docblocks carry an interactive example that loads WordPress by hand:

• WP_HTML_Processor::class_list()
• WP_HTML_Tag_Processor::class_list()

Interactive examples in the Code Reference run in WordPress Playground. Playground now prepends the bootstrap before it runs a snippet (WordPress/wordpress-playground#4262), and the Code Reference theme loads WordPress before the snippet (WordPress/wporg-developer#579). The leading <?php and the require '/wordpress/wp-load.php'; do nothing now, and readers still see them in the rendered example. This removes both.

The examples also print with echo and state the output in a trailing comment instead of a separate expected-output block.

See:

• ​https://github.com/WordPress/wordpress-playground/pull/4262
• ​https://github.com/WordPress/wporg-developer/pull/579

## Use of AI Tools

• AI assistance: Yes
• Tool(s): Claude Code
• Model(s): Claude Opus 5
• Used for: This pull request description. The code change is mine.

[peterwilsoncc]

In 63403:

Docs: Document functions within embed-template.js.

See #65860.

[zieladam]

In 63463:

HTML API: Simplify interactive class_list() examples.

Removes the PHP opening tag and manual WordPress bootstrap now that WordPress Playground and the Code Reference load WordPress before running interactive examples. Prints each class name directly and places the expected output in a trailing comment.

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

Follow-up to r63293.

Props jonsurrell, dmsnell.
See #65860.

Merged in r63463.

[wildworks]

In 63498:

Bundled Themes: Document the parameters of five template functions.

Adds missing @param/@return tags to five Twenty Nineteen and Twenty Twelve functions.

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

Props bejignesh, mukesh27, wildworks.
See #65860.

Committed: https://core.trac.wordpress.org/changeset/63498

[westonruter]

In 63511:

Code Quality: Improve typing for wp_array_slice_assoc().

The @param and @return tags have documented a bare array since the function was introduced in r15574, so nothing was known about the slice it returns. They now describe the string-keyed arrays the function accepts, PHPStan generics bind the returned key set to the $keys argument so that a call passing a known list of keys resolves to those keys rather than to string. The signature also gains a native array return type.

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

See #65817, #65860.

[jonsurrell]

In 63515:

HTML API: Clarify parse_next_attribute() return value.

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

Follow-up to r62595.

Props jonsurrell, dmsnell.
See #65860, #65372.

Merged in r63515.

[westonruter]

In 63522:

Code Quality: Improve typing for wp_parse_args().

Both the parameters and the return value have been documented as a bare array since the function entered trunk in r5234. They now describe the string-keyed arrays it is used with, and the signature gains a native array return type. Every caller treats those keys as strings, but the function cannot guarantee it, since get_object_vars() reports a numeric-string property under an integer key and parse_str() reads 0=a as one, so the @phpstan-return records what can actually come back.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/13430.
Follow-up to r5234, r47429.

See #65817, #65860.

[westonruter]

In 63524:

Code Quality: Combine registered block styles with array_merge().

In WP_REST_Block_Types_Controller the block styles registered for a block are combined with array_merge(), where wp_parse_args() had been used erroneously on what are two lists. In support of this, a global Block_Style_Properties type alias is introduced for the shape of a registered block style.

Developed in ​https://github.com/WordPress/wordpress-develop/pull/13432.
Follow-up to r48173, r59760, r63522.

Props westonruter, swissspidy.
See #65817, #65860.

[audrasjb]

In 63569:

Docs: Replace @see with @link in WP_Site_Icon various docblocks.

This changeset ensures these external links declaration is consistent with WordPress/PHP Documentation Standards.

See #65860.

### Why this change?

The ​PHP inline documentation standards state, in the @param, @return and @global sections:

For boolean and integer types, use bool and int, respectively.

Six docblocks in core code still used the long forms. This brings them in line.

File	Tag
wp-includes/class-wp-theme-json.php	@param boolean $use_root_padding
wp-includes/global-styles-and-settings.php	@param boolean $fallback
wp-includes/html-api/class-wp-html-tag-processor.php	@return string\||boolean\||null
wp-includes/media.php	@param boolean $enabled
wp-includes/rest-api/endpoints/class-wp-rest-global-styles-controller.php	@param integer $id
wp-includes/rest-api/endpoints/class-wp-rest-templates-controller.php	@param integer $id

### Notes on scope

Parameter columns are realigned where needed. In class-wp-theme-json.php, shortening boolean makes string the longest type in that block, so the whole @param column shifts left by one to stay aligned. That is why the file shows six changed lines rather than one.

Bundled third-party libraries are left untouched. Services_JSON (wp-includes/class-json.php) alone has four more instances, but core does not take style changes to vendored code.

The prose in class-wp-html-tag-processor.php is left alone. The description above the tag reads "If an update is enqueued and is boolean, the return will be true". That is English describing a value, not a type declaration, so the standard does not apply to it.

After this change, src/ has no remaining boolean or integer types in core PHP docblocks.

### Testing

• php -l clean on all six files.
• phpcs --standard=phpcs.xml.dist reports 0 errors on all six files. There is one pre-existing warning at media.php:5723 (WordPress.DB.PreparedSQL.NotPrepared), unrelated to this change and ~3,600 lines away from it; I confirmed it is present on trunk without this patch.

Documentation only, no behaviour change, so no test changes are needed.

## Use of AI Tools

AI assistance: Yes
Tool(s): Claude Code
Model(s): Claude Opus 5
Used for: Scanning src/ for the long-form types, which is how these six were found, applying the substitutions and column realignment, and drafting this description. I checked each site against the current file, confirmed the third-party exclusions, verified the pre-existing phpcs warning is present on trunk without this patch, confirmed no open pull request already touches these docblocks, ran php -l and phpcs, and I take responsibility for the result.

[westonruter]

In 63596:

Docs: Use the bool and int short type forms in PHPDoc.

The PHP inline documentation standards call for bool and int in @param, @return and @global tags, but six docblocks in src/wp-includes still carried the long boolean and integer spellings.

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

Props njones35.
See #65860.