Navigation: Complete the DocBlocks for the responsive container and overlay style helpers

[itzmekhokan]

What?

See https://core.trac.wordpress.org/ticket/65691
Follow up to WordPress/wordpress-develop#12640

WP_Navigation_Block_Renderer::get_overlay_inline_styles(), introduced in WordPress 7.0.0, documented only its second parameter, $colors. Its first parameter, $has_custom_overlay, had no @param entry.

This adds the missing tag, aligns the @param columns in that method and in its sibling get_responsive_container_classes(), and adds @phpstan-param array shapes for the $colors keys each method reads.

Why?

The fix was originally proposed against Core in WordPress/wordpress-develop#12640, where @westonruter pointed out that this file is managed in the Gutenberg repo and the change needs to be made here first:

The tests are failing because this file is managed in the Gutenberg repo. You'll need to make the fix there.

He also suggested taking the opportunity to provide the full PHPStan typing for $colors while the DocBlock is being touched.

An undocumented parameter is a documentation standards violation, and the missing entry is easy to miss because the remaining @param array $colors line makes the block look complete at a glance.

How?

• Added @param bool $has_custom_overlay to get_overlay_inline_styles(), in signature order.
• Aligned the @param description columns in both methods per the WordPress PHP documentation standards. get_responsive_container_classes() had the same misalignment, so it is corrected here rather than left for a follow up.
• Added @phpstan-param array shapes documenting only the keys each method actually reads:
  • get_overlay_inline_styles() reads overlay_inline_styles (a string).
  • get_responsive_container_classes() reads overlay_css_classes (a list<string>, passed to implode()).

Both keys are produced by block_core_navigation_build_css_colors(), which returns css_classes, inline_styles, overlay_css_classes and overlay_inline_styles. The shapes follow the existing convention in lib/block-supports/custom-css.php and lib/block-supports/elements.php, placing the tag after @return.

Documentation only; no behavior is affected.

Testing Instructions

This is a documentation-only change, so there is nothing to exercise in the editor. To verify:

1. Run composer lint -- packages/block-library/src/navigation/index.php and confirm it passes.
2. Open packages/block-library/src/navigation/index.php and confirm the DocBlocks for get_responsive_container_classes() and get_overlay_inline_styles() list every parameter in signature order with aligned columns.

To confirm no runtime change, compare the PHP token stream against trunk with comments and whitespace stripped; it is byte-identical (5949 tokens, matching checksum).

Testing Instructions for Keyboard

N/A. No user interface changes.

Screenshots or screencast

N/A. No user interface changes.

Use of AI Tools

This pull request was prepared with the assistance of Claude Code. The AI was used to locate the affected DocBlocks, apply the changes, and run verification (PHPCS with the repository ruleset, php -l, PHPStan checks of the array shapes, and a token stream comparison against trunk). I reviewed the resulting diff and the verification output, and I take responsibility for the contents of this pull request.

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

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: itzmekhokan <khokansardar@git.wordpress.org>
Co-authored-by: shail-mehta <shailu25@git.wordpress.org>
Co-authored-by: westonruter <westonruter@git.wordpress.org>

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

[shail-mehta]

LGTM👍

[Copilot]

Pull request overview

Completes and improves PHPDoc/PHPStan documentation for Navigation responsive overlay helpers without runtime changes.

Changes:

• Documents the missing $has_custom_overlay parameter.
• Aligns parameter descriptions and adds precise $colors array shapes.