From 78c6714f79462f81e7dfdff45142f54105d80ba6 Mon Sep 17 00:00:00 2001
From: Tomas Votruba <tomas.vot@gmail.com>
Date: Sat, 10 Oct 2026 10:41:36 +0200
Subject: [PATCH] Keep phpdoc @param on expression statements in blink
 NoSuperfluousPhpdocTags

A docblock before an expression statement (e.g. a method call taking a closure) was misread as a property declaration, so its @param tags were dropped as unused params. Reject a bare variable as the first token after the docblock unless a modifier preceded it.
---
 .../fixer/rules/no_superfluous_phpdoc_tags.go      | 13 +++++++++++--
 .../fixer/rules/no_superfluous_phpdoc_tags_test.go | 14 ++++++++++++++
 2 files changed, 25 insertions(+), 2 deletions(-)

diff --git a/blink/internal/fixer/rules/no_superfluous_phpdoc_tags.go b/blink/internal/fixer/rules/no_superfluous_phpdoc_tags.go
index ddf69ef71a..c155dc3be1 100644
--- a/blink/internal/fixer/rules/no_superfluous_phpdoc_tags.go
+++ b/blink/internal/fixer/rules/no_superfluous_phpdoc_tags.go
@@ -285,6 +285,7 @@ type funcSig struct {
 func signatureAfter(s *tokens.Stream, doc int) (funcSig, bool) {
 	// Walk forward across whitespace, attributes (#[...] Comment) and modifier
 	// keywords to the "function" keyword.
+	sawModifier := false
 	j := doc + 1
 	for j < s.Len() {
 		t := s.At(j)
@@ -301,13 +302,21 @@ func signatureAfter(s *tokens.Stream, doc int) (funcSig, bool) {
 				return funcSig{}, false
 			}
 			if lv == "var" || isFuncModifier(lv) || lv == "readonly" {
+				sawModifier = true
 				j++
 				continue
 			}
 			// a typed property whose type is a reserved word (e.g. "array")
 			return parseProperty(s, j)
-		case token.Ident, token.Punct, token.Variable:
-			// a property: "Foo $x", "?Foo $x", "\Foo\Bar $x", or untyped "$x"
+		case token.Ident, token.Punct:
+			// a property: "Foo $x", "?Foo $x", "\Foo\Bar $x"
+			return parseProperty(s, j)
+		case token.Variable:
+			// a bare variable with no preceding modifier/type is an expression
+			// statement (e.g. "$this->foo()"), not a property declaration
+			if !sawModifier {
+				return funcSig{}, false
+			}
 			return parseProperty(s, j)
 		default:
 			return funcSig{}, false
diff --git a/blink/internal/fixer/rules/no_superfluous_phpdoc_tags_test.go b/blink/internal/fixer/rules/no_superfluous_phpdoc_tags_test.go
index 1a694099e4..bd4620d319 100644
--- a/blink/internal/fixer/rules/no_superfluous_phpdoc_tags_test.go
+++ b/blink/internal/fixer/rules/no_superfluous_phpdoc_tags_test.go
@@ -96,6 +96,20 @@ func TestNoSuperfluousPhpdocTags(t *testing.T) {
 		"<?php\n/**\n * Does a thing.\n *\n */\nfunction f(int $n) {}", true)
 }
 
+// A docblock documenting a closure parameter, placed before an expression
+// statement (a method call taking the closure), is not attached to a function or
+// property declaration, so its @param must be kept even with allow_unused_params.
+func TestNoSuperfluousPhpdocTagsKeepsDocBeforeExpression(t *testing.T) {
+	t.Parallel()
+	f := NoSuperfluousPhpdocTags{}.WithConfig(map[string]any{"allow_unused_params": false}).(fixerRule)
+
+	src := "<?php\nclass A {\n    public function run(array $stmts): void\n    {\n" +
+		"        /** @param Use_::TYPE_* $useType */\n" +
+		"        $this->traverser->traverse($stmts, static function (int $useType) {});\n" +
+		"    }\n}\n"
+	assertFix(t, f, src, src, false)
+}
+
 func TestNoSuperfluousPhpdocTagsSourceURL(t *testing.T) {
 	t.Parallel()
 	f := NoSuperfluousPhpdocTags{}