Keep phpdoc @param on expression statements in blink NoSuperfluousPhpdocTags

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

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{}