Docs: Reconcile hash notation with the values callers pass

[swissspidy]

Several hashes describe a narrower type than the code on either side of them uses. Where the documented type is the one that is wrong, this widens it; where the caller is, it corrects the caller to what the hash already says.

These surfaced while teaching PHPStan to read hash notation in #13233, but each is a disagreement between a docblock and the code that stands on its own, so they are split out here rather than carried in that pull request's baselines.

Documentation

WP_Ajax_Response::add()	documents $id as int|WP_Error and $position as string. Every caller in wp-admin passes a numeric string for the first and an int for the second — which is what the $position description already says: "Accepts 1 (bottom), -1 (top)"
get_bookmarks()	documents $category as a comma-separated list of IDs. The links list table passes a single ID as an int, which wp_parse_id_list() accepts
wp_list_pages()	documents $title_li as string, in a description reading "Passing a null or empty value will result in no heading". Twenty Twenty passes false to get exactly that
wp_nav_menu()	documents $container as string, in a description beginning "Whether to wrap the ul". Twenty Twenty-One passes false not to
WP_Customize_Setting::$default	is documented string and holds whatever the setting's default is

$default is the interesting one: two subclasses already redeclare it as array, and one assignment of a stdClass exists. All three were reported and baselined — typing the property mixed removes those three entries. This pull request is a net reduction in the baselines.

Call sites

WP_MS_Themes_List_Table	passes 'inline' for wp_admin_notice()'s $additional_classes, which takes a list of classes
Twenty Nineteen	passes null for comment_form()'s $title_reply, where an empty string suppresses the heading just as well
Twenty Twenty	passes '' for wp_nav_menu()'s $fallback_cb, which takes callable|false
WP_Customize_Manager	passes 0 for get_pages()'s $hierarchical, which takes a bool

Each caller change is behaviourally identical to what it replaces — the values are already falsy or already accepted — so this is about saying the same thing in the documented type.

What is not here

The same exercise surfaced call sites that no docblock change reaches, because the array reaching them has no statically known keys — five wp_insert_post() callers, get_pages() in post-template.php, register_sidebar() in widgets.php. One more, WP_Customize_Manager::get_changeset_posts(), wants get_post_stati() to say which of string[] or stdClass[] it returns for a given $output, which is a separate change. Those are left alone.

Testing

composer phpstan is green, from a cleared result cache, and composer lint reports nothing new on the changed files. The docblock realignments are column-only where a widened type changed the width.

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

Shares a ticket with #13233 for now; happy to move it to its own.

Use of AI Tools

AI assistance: Yes
Tool(s): Claude Code
Used for: finding these disagreements by running the analysis with #13233's extension enabled, checking each against the code, and drafting the corrections and this description.

---

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 by Claude Code

[github-actions]

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

• All changes will be lost when closing a tab with a Playground instance.
• All changes will be lost when refreshing the page.
• A fresh instance is created each time the link below is clicked.
• Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
  it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Unlinked Accounts

The following contributors have not linked their GitHub and WordPress.org accounts: @claude.

Contributors, please read how to link your accounts to ensure your work is properly credited in WordPress releases.

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.