From b0068e10e6597231a1dfb68a858db65b1cf19f92 Mon Sep 17 00:00:00 2001
From: kkmuffme <11071985+kkmuffme@users.noreply.github.com>
Date: Sat, 3 Jan 2026 13:33:37 +0100
Subject: [PATCH 1/5] Don't count undocumented globals as duplicates if only
 checking documented globals

---
 src/NodeVisitor.php | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/src/NodeVisitor.php b/src/NodeVisitor.php
index 0e631dc..42354e3 100644
--- a/src/NodeVisitor.php
+++ b/src/NodeVisitor.php
@@ -404,12 +404,13 @@ function (\PhpParser\Node\Const_ $const) {
             && $node->expr->var instanceof Variable
             && is_string($node->expr->var->name)
         ) {
-            $this->count('globals', $node->expr->var->name);
             // We'll keep regular global variable declarations, depending on
             // whether or not they are documented.
-            if ($node->getDocComment()) {
+            if ($this->needsDocumentedGlobals && $node->getDocComment()) {
+                $this->count('globals', $node->expr->var->name);
                 return $this->needsDocumentedGlobals;
-            } else {
+            } elseif ($this->needsUndocumentedGlobals) {
+                $this->count('globals', $node->expr->var->name);
                 return $this->needsUndocumentedGlobals;
             }
         }

From e30a174ebca39292f715e5a8fd2869b2b90a53e5 Mon Sep 17 00:00:00 2001
From: kkmuffme <11071985+kkmuffme@users.noreply.github.com>
Date: Sat, 3 Jan 2026 13:38:05 +0100
Subject: [PATCH 2/5] Don't count constants in conditions as duplicates

---
 src/NodeVisitor.php | 19 +++++++++++++++----
 1 file changed, 15 insertions(+), 4 deletions(-)

diff --git a/src/NodeVisitor.php b/src/NodeVisitor.php
index 42354e3..6938536 100644
--- a/src/NodeVisitor.php
+++ b/src/NodeVisitor.php
@@ -376,8 +376,14 @@ private function needsNode(Node $node, string $namespace): bool
                     $node->consts,
                     function (\PhpParser\Node\Const_ $const) {
                         $fullyQualifiedName = $const->name->name;
-                        return $this->count('constants', $fullyQualifiedName)
-                            && !defined($fullyQualifiedName);
+
+                        if (
+                            !$this->isInIf ||
+                            !isset($this->counts['constants'][$fullyQualifiedName])
+                        ) {
+                            return $this->count('constants', $fullyQualifiedName)
+                                   && !defined($fullyQualifiedName);
+                        }
                     }
                 );
 
@@ -392,8 +398,13 @@ function (\PhpParser\Node\Const_ $const) {
             ) {
                 $fullyQualifiedName = $node->expr->args[0]->value->value;
 
-                return $this->count('constants', $fullyQualifiedName)
-                    && !defined($fullyQualifiedName);
+                if (
+                    !$this->isInIf ||
+                    !isset($this->counts['constants'][$fullyQualifiedName])
+                ) {
+                    return $this->count('constants', $fullyQualifiedName)
+                           && !defined($fullyQualifiedName);
+                }
             }
         }
 

From 3808de11db36a64ad8bf699a4ff4295dc1575e0b Mon Sep 17 00:00:00 2001
From: kkmuffme <11071985+kkmuffme@users.noreply.github.com>
Date: Sat, 3 Jan 2026 14:10:19 +0100
Subject: [PATCH 3/5] globals without @var in comment are not documented

Common false positive in WordPress where a global is annotated with @param since it's assigned the result of an apply_filters
---
 src/NodeVisitor.php | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/src/NodeVisitor.php b/src/NodeVisitor.php
index 6938536..0e820b9 100644
--- a/src/NodeVisitor.php
+++ b/src/NodeVisitor.php
@@ -417,10 +417,13 @@ function (\PhpParser\Node\Const_ $const) {
         ) {
             // We'll keep regular global variable declarations, depending on
             // whether or not they are documented.
-            if ($this->needsDocumentedGlobals && $node->getDocComment()) {
+            // Only @var comments are actual, useful documentation for stubs
+			$hasValidComment = $node->getDocComment() && preg_match('/@(?:[a-z]+-)?var\s/', $node->getDocComment()->getText());
+
+            if ($this->needsDocumentedGlobals && $hasValidComment) {
                 $this->count('globals', $node->expr->var->name);
                 return $this->needsDocumentedGlobals;
-            } elseif ($this->needsUndocumentedGlobals) {
+            } elseif ($this->needsUndocumentedGlobals && !$hasValidComment) {
                 $this->count('globals', $node->expr->var->name);
                 return $this->needsUndocumentedGlobals;
             }

From 7c2eaa278a92a16f6a733b623f02df9319fbc911 Mon Sep 17 00:00:00 2001
From: kkmuffme <11071985+kkmuffme@users.noreply.github.com>
Date: Sat, 3 Jan 2026 14:23:10 +0100
Subject: [PATCH 4/5] update tests and add test for doc in constant

---
 test/files/constants.in.php          | 10 ++++++++++
 test/files/constants.out.php         |  8 ++++++++
 test/files/globals.all.out.php       | 10 ++++++++--
 test/files/globals.doc.out.php       |  4 ++--
 test/files/globals.in.php            | 10 ++++++++--
 test/files/globals.no-doc.out.php    |  6 ++++++
 test/files/globals.nullified.out.php | 10 ++++++++--
 7 files changed, 50 insertions(+), 8 deletions(-)

diff --git a/test/files/constants.in.php b/test/files/constants.in.php
index b9e2471..c0e71f1 100644
--- a/test/files/constants.in.php
+++ b/test/files/constants.in.php
@@ -7,3 +7,13 @@
 define('FIZ', 'BUZ');
 
 const A = 1, B = 2;
+
+if (!defined('ACME')) {
+    define('ACME', 1);
+}
+
+if (!defined('ACME')) {
+    define('ACME', 2);
+}
+
+\define( 'FOOBAR', /** @var int */ 0 );
diff --git a/test/files/constants.out.php b/test/files/constants.out.php
index 8db4891..6c3e9ce 100644
--- a/test/files/constants.out.php
+++ b/test/files/constants.out.php
@@ -7,3 +7,11 @@
 \define('FIZ', 'BUZ');
 
 const A = 1, B = 2;
+
+\define('ACME', 1);
+
+\define(
+    'FOOBAR',
+    /** @var int */
+    0
+);
diff --git a/test/files/globals.all.out.php b/test/files/globals.all.out.php
index 710d9fc..fc08f17 100644
--- a/test/files/globals.all.out.php
+++ b/test/files/globals.all.out.php
@@ -1,10 +1,16 @@
 <?php
-/** doc */
+/** @var string */
 $a = 'a' . 'a';
 
-/** @doc */
+/** @var string $b */
 $b = 'b' . 'b';
 
 $c = 'c' . 'c';
 
 $d = 'd' . 'd';
+
+/** doc */
+$x = 'x' . 'x';
+
+/** @doc */
+$y = 'y' . 'y';
diff --git a/test/files/globals.doc.out.php b/test/files/globals.doc.out.php
index cde9680..c7f2f9d 100644
--- a/test/files/globals.doc.out.php
+++ b/test/files/globals.doc.out.php
@@ -1,6 +1,6 @@
 <?php
-/** doc */
+/** @var string */
 $a = 'a' . 'a';
 
-/** @doc */
+/** @var string $b */
 $b = 'b' . 'b';
diff --git a/test/files/globals.in.php b/test/files/globals.in.php
index ce090d8..8c73b3a 100644
--- a/test/files/globals.in.php
+++ b/test/files/globals.in.php
@@ -1,8 +1,8 @@
 <?php
-/** doc */
+/** @var string */
 $a = 'a' . 'a';
 
-/** @doc */
+/** @var string $b */
 $GLOBALS['b'] = 'b' . 'b';
 
 $c = 'c' . 'c';
@@ -25,3 +25,9 @@
 
 function () {
 };
+
+/** doc */
+$x = 'x' . 'x';
+
+/** @doc */
+$GLOBALS['y'] = 'y' . 'y';
diff --git a/test/files/globals.no-doc.out.php b/test/files/globals.no-doc.out.php
index 7e3e5cb..b726313 100644
--- a/test/files/globals.no-doc.out.php
+++ b/test/files/globals.no-doc.out.php
@@ -2,3 +2,9 @@
 $c = 'c' . 'c';
 
 $d = 'd' . 'd';
+
+/** doc */
+$x = 'x' . 'x';
+
+/** @doc */
+$y = 'y' . 'y';
diff --git a/test/files/globals.nullified.out.php b/test/files/globals.nullified.out.php
index e405853..d00aea3 100644
--- a/test/files/globals.nullified.out.php
+++ b/test/files/globals.nullified.out.php
@@ -1,10 +1,16 @@
 <?php
-/** doc */
+/** @var string */
 $a = \null;
 
-/** @doc */
+/** @var string $b */
 $b = \null;
 
 $c = \null;
 
 $d = \null;
+
+/** doc */
+$x = \null;
+
+/** @doc */
+$y = \null;

From 11e677e6a8bb42279f3315514330cd26f862c298 Mon Sep 17 00:00:00 2001
From: kkmuffme <11071985+kkmuffme@users.noreply.github.com>
Date: Sat, 3 Jan 2026 16:25:27 +0100
Subject: [PATCH 5/5] remove comments from undocumented globals

---
 src/NodeVisitor.php                  | 12 ++++++++++--
 test/files/globals.all.out.php       |  2 --
 test/files/globals.no-doc.out.php    |  2 --
 test/files/globals.nullified.out.php |  2 --
 4 files changed, 10 insertions(+), 8 deletions(-)

diff --git a/src/NodeVisitor.php b/src/NodeVisitor.php
index 0e820b9..27207c0 100644
--- a/src/NodeVisitor.php
+++ b/src/NodeVisitor.php
@@ -418,13 +418,21 @@ function (\PhpParser\Node\Const_ $const) {
             // We'll keep regular global variable declarations, depending on
             // whether or not they are documented.
             // Only @var comments are actual, useful documentation for stubs
-			$hasValidComment = $node->getDocComment() && preg_match('/@(?:[a-z]+-)?var\s/', $node->getDocComment()->getText());
+            $hasValidComment = $node->getDocComment() && preg_match('/@(?:[a-z]+-)?var\s/', $node->getDocComment()->getText());
 
             if ($this->needsDocumentedGlobals && $hasValidComment) {
                 $this->count('globals', $node->expr->var->name);
                 return $this->needsDocumentedGlobals;
-            } elseif ($this->needsUndocumentedGlobals && !$hasValidComment) {
+            }
+
+            if ($this->needsUndocumentedGlobals && !$hasValidComment) {
                 $this->count('globals', $node->expr->var->name);
+
+                // remove useless comments
+                if ($node->getComments() !== []) {
+                    $node->setAttribute('comments', []);
+                }
+
                 return $this->needsUndocumentedGlobals;
             }
         }
diff --git a/test/files/globals.all.out.php b/test/files/globals.all.out.php
index fc08f17..3ed76ab 100644
--- a/test/files/globals.all.out.php
+++ b/test/files/globals.all.out.php
@@ -9,8 +9,6 @@
 
 $d = 'd' . 'd';
 
-/** doc */
 $x = 'x' . 'x';
 
-/** @doc */
 $y = 'y' . 'y';
diff --git a/test/files/globals.no-doc.out.php b/test/files/globals.no-doc.out.php
index b726313..f995242 100644
--- a/test/files/globals.no-doc.out.php
+++ b/test/files/globals.no-doc.out.php
@@ -3,8 +3,6 @@
 
 $d = 'd' . 'd';
 
-/** doc */
 $x = 'x' . 'x';
 
-/** @doc */
 $y = 'y' . 'y';
diff --git a/test/files/globals.nullified.out.php b/test/files/globals.nullified.out.php
index d00aea3..480ccb2 100644
--- a/test/files/globals.nullified.out.php
+++ b/test/files/globals.nullified.out.php
@@ -9,8 +9,6 @@
 
 $d = \null;
 
-/** doc */
 $x = \null;
 
-/** @doc */
 $y = \null;