From 9947148e272f5d739ecad4ab7d2e1f79f4ece6de Mon Sep 17 00:00:00 2001
From: Tomas Votruba <tomas.vot@gmail.com>
Date: Wed, 16 Sep 2026 10:26:36 +0200
Subject: [PATCH] Drop @param mixed docblocks once a real type is added

---
 internal/phpast/docparam_test.go | 10 ++++++++--
 internal/phpast/phpast.go        | 12 +++++++++++-
 2 files changed, 19 insertions(+), 3 deletions(-)

diff --git a/internal/phpast/docparam_test.go b/internal/phpast/docparam_test.go
index 65607a75..21ec28fa 100644
--- a/internal/phpast/docparam_test.go
+++ b/internal/phpast/docparam_test.go
@@ -39,10 +39,16 @@ func TestStripRedundantDocParams(t *testing.T) {
 			want:  "<?php\nclass A {\n    public function m($e) {}\n}",
 		},
 		{
-			name:  "keeps a tag whose type differs from the added type",
+			name:  "drops a mixed tag once any type is added",
 			src:   "<?php\nclass A {\n    /**\n     * @param mixed $v\n     */\n    public function m($v) {}\n}",
 			added: map[string]string{"v": "\\DateTime"},
-			want:  "<?php\nclass A {\n    /**\n     * @param mixed $v\n     */\n    public function m($v) {}\n}",
+			want:  "<?php\nclass A {\n    public function m($v) {}\n}",
+		},
+		{
+			name:  "keeps a tag whose type differs from the added type",
+			src:   "<?php\nclass A {\n    /**\n     * @param int $v\n     */\n    public function m($v) {}\n}",
+			added: map[string]string{"v": "\\DateTime"},
+			want:  "<?php\nclass A {\n    /**\n     * @param int $v\n     */\n    public function m($v) {}\n}",
 		},
 	}
 
diff --git a/internal/phpast/phpast.go b/internal/phpast/phpast.go
index 993ca18b..4dcb110a 100644
--- a/internal/phpast/phpast.go
+++ b/internal/phpast/phpast.go
@@ -177,7 +177,7 @@ func stripDocParamLines(doc string, added map[string]string) (result string, cha
 	for i := 0; i < len(lines); i++ {
 		line := lines[i]
 		if match := docParamLine.FindStringSubmatch(line); match != nil {
-			if native, ok := added[match[2]]; ok && normalizeDocType(match[1]) == normalizeDocType(native) {
+			if native, ok := added[match[2]]; ok && docTypeRedundant(match[1], native) {
 				changed = true
 				// also drop a blank comment line that followed the tag
 				if i+1 < len(lines) && isBlankCommentLine(lines[i+1]) {
@@ -219,6 +219,16 @@ func docIsEmpty(lines []string) bool {
 // union member order and of whether a class is written as a short name or a
 // fully qualified one: each member is cut to its last name part and the members
 // are sorted.
+// docTypeRedundant reports whether a `@param` type adds nothing over the type
+// just written on the parameter: either it equals the added type, or it is
+// `mixed`, which carries no information once a real type is present.
+func docTypeRedundant(docType, native string) bool {
+	if strings.EqualFold(docType, "mixed") {
+		return true
+	}
+	return normalizeDocType(docType) == normalizeDocType(native)
+}
+
 func normalizeDocType(name string) string {
 	parts := strings.Split(name, "|")
 	for i, part := range parts {