From 2cf24b3b14db5d2f45d59c1ab4216313629d5d1d Mon Sep 17 00:00:00 2001
From: Marc Ginesta <mginesta@adobe.com>
Date: Wed, 31 Aug 2022 17:18:14 +0200
Subject: [PATCH 1/5] Implement changes approved to @see tag in Dev guild

---
 .../Commenting/PHPDocFormattingValidator.php  |  7 ++++++-
 .../MethodAnnotationStructureUnitTest.inc     | 20 +++++++++++++++++++
 ...AndInterfacePHPDocFormattingUnitTest.1.inc | 17 ++++++++++++++++
 ...AndInterfacePHPDocFormattingUnitTest.2.inc | 16 +++++++++++++++
 .../ClassPropertyPHPDocFormattingUnitTest.inc |  6 ++++++
 .../ConstantsPHPDocFormattingUnitTest.2.inc   | 10 ++++++++++
 6 files changed, 75 insertions(+), 1 deletion(-)

diff --git a/Magento2/Helpers/Commenting/PHPDocFormattingValidator.php b/Magento2/Helpers/Commenting/PHPDocFormattingValidator.php
index 9fd42e7f..3421b8a1 100644
--- a/Magento2/Helpers/Commenting/PHPDocFormattingValidator.php
+++ b/Magento2/Helpers/Commenting/PHPDocFormattingValidator.php
@@ -13,6 +13,8 @@
  */
 class PHPDocFormattingValidator
 {
+    private const REMOVED_IN_VERSION = 'removed in version';
+
     /**
      * Finds matching PHPDoc for current pointer
      *
@@ -123,7 +125,10 @@ public function hasDeprecatedWellFormatted($commentStartPtr, $tokens)
         }
         $seePtr = $this->getTagPosition('@see', $commentStartPtr, $tokens);
         if ($seePtr === -1) {
-            return false;
+            if (!stripos($tokens[$deprecatedPtr + 2]['content'], self::REMOVED_IN_VERSION, 0)) {
+                return false;
+            }
+            return true;
         }
 
         return $tokens[$seePtr + 2]['code'] === T_DOC_COMMENT_STRING;
diff --git a/Magento2/Tests/Annotation/MethodAnnotationStructureUnitTest.inc b/Magento2/Tests/Annotation/MethodAnnotationStructureUnitTest.inc
index 4d3e0b7b..6b7431c9 100644
--- a/Magento2/Tests/Annotation/MethodAnnotationStructureUnitTest.inc
+++ b/Magento2/Tests/Annotation/MethodAnnotationStructureUnitTest.inc
@@ -369,4 +369,24 @@ class MethodAnnotationFixture
     {
         return true;
     }
+
+    /**
+     * This deprecated function is correct even though it only contains the @deprecated tag.
+     *
+     * @deprecated It will be removed in version 1.0.0
+     */
+    public function correctBecauseOfKeywordPhrase()
+    {
+        return false;
+    }
+
+    /**
+     * This deprecated function is correct even though it only contains the @deprecated tag.
+     *
+     * @deprecated WOW! It will be removed in version 1.0.0
+     */
+    public function alsoCorrectBecauseOfKeywordPhrase()
+    {
+        return false;
+    }
 }
diff --git a/Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.1.inc b/Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.1.inc
index e5895e32..c9785e18 100644
--- a/Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.1.inc
+++ b/Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.1.inc
@@ -162,3 +162,20 @@ class OldHandler
 {
 
 }
+
+/**
+ * @deprecated It will be removed in version 1.0.0
+ */
+class DeprecatedButHandler
+{
+
+}
+
+/**
+ * @deprecated It's also deprecated, but it will be removed in version 1.0.0
+ */
+class AlsoDeprecatedButHandler
+{
+
+}
+
diff --git a/Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.2.inc b/Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.2.inc
index 96900de2..62935860 100644
--- a/Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.2.inc
+++ b/Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.2.inc
@@ -153,3 +153,19 @@ interface DoNotCareHandler
 {
 
 }
+
+/**
+ * @deprecated This interface will be removed in version 1.0.0
+ */
+interface DeprecatedButHandler
+{
+
+}
+
+/**
+ * @deprecated Yeah! This interface will be removed in version 1.0.0
+ */
+interface AlsoDeprecatedButHandler
+{
+
+}
diff --git a/Magento2/Tests/Commenting/ClassPropertyPHPDocFormattingUnitTest.inc b/Magento2/Tests/Commenting/ClassPropertyPHPDocFormattingUnitTest.inc
index 62e9688f..1c85b175 100644
--- a/Magento2/Tests/Commenting/ClassPropertyPHPDocFormattingUnitTest.inc
+++ b/Magento2/Tests/Commenting/ClassPropertyPHPDocFormattingUnitTest.inc
@@ -194,4 +194,10 @@ class correctlyFormattedClassMemberDocBlock
      * @see Message with some reference
      */
     protected string $itIsCorrect;
+
+    /**
+     * @var string
+     * @deprecated This property will be removed in version 1.0.0
+     */
+    protected string $deprecatedWithKeyword;
 }
diff --git a/Magento2/Tests/Commenting/ConstantsPHPDocFormattingUnitTest.2.inc b/Magento2/Tests/Commenting/ConstantsPHPDocFormattingUnitTest.2.inc
index 12b89834..a75730e6 100644
--- a/Magento2/Tests/Commenting/ConstantsPHPDocFormattingUnitTest.2.inc
+++ b/Magento2/Tests/Commenting/ConstantsPHPDocFormattingUnitTest.2.inc
@@ -63,4 +63,14 @@ class Profiler
      * @see
      */
     const d = 100;
+
+    /**
+     * @deprecated This constant will be removed in version 1.0.0
+     */
+    const KEYWORD_PHRASE = false;
+
+    /**
+     * @deprecated It's awesome - This constant will be removed in version 1.0.0
+     */
+    const WITH_KEYWORD_PHRASE = false;
 }

From 922e1080bde3ed1560075fa87fc10720097a3b9a Mon Sep 17 00:00:00 2001
From: Marc Ginesta <mginesta@adobe.com>
Date: Wed, 31 Aug 2022 17:57:49 +0200
Subject: [PATCH 2/5] Add without replacement

---
 Magento2/Helpers/Commenting/PHPDocFormattingValidator.php | 8 +++++---
 .../Annotation/MethodAnnotationStructureUnitTest.inc      | 4 ++--
 .../ClassAndInterfacePHPDocFormattingUnitTest.1.inc       | 4 ++--
 .../ClassAndInterfacePHPDocFormattingUnitTest.2.inc       | 4 ++--
 .../Commenting/ClassPropertyPHPDocFormattingUnitTest.inc  | 2 +-
 .../Commenting/ConstantsPHPDocFormattingUnitTest.2.inc    | 4 ++--
 6 files changed, 14 insertions(+), 12 deletions(-)

diff --git a/Magento2/Helpers/Commenting/PHPDocFormattingValidator.php b/Magento2/Helpers/Commenting/PHPDocFormattingValidator.php
index 3421b8a1..a5f33d8c 100644
--- a/Magento2/Helpers/Commenting/PHPDocFormattingValidator.php
+++ b/Magento2/Helpers/Commenting/PHPDocFormattingValidator.php
@@ -14,6 +14,7 @@
 class PHPDocFormattingValidator
 {
     private const REMOVED_IN_VERSION = 'removed in version';
+    private const WITHOUT_REPLACEMENT = 'without replacement';
 
     /**
      * Finds matching PHPDoc for current pointer
@@ -125,10 +126,11 @@ public function hasDeprecatedWellFormatted($commentStartPtr, $tokens)
         }
         $seePtr = $this->getTagPosition('@see', $commentStartPtr, $tokens);
         if ($seePtr === -1) {
-            if (!stripos($tokens[$deprecatedPtr + 2]['content'], self::REMOVED_IN_VERSION, 0)) {
-                return false;
+            if (stripos($tokens[$deprecatedPtr + 2]['content'], self::REMOVED_IN_VERSION, 0) &&
+                stripos($tokens[$deprecatedPtr + 2]['content'], self::WITHOUT_REPLACEMENT, 0)) {
+                return true;
             }
-            return true;
+            return false;
         }
 
         return $tokens[$seePtr + 2]['code'] === T_DOC_COMMENT_STRING;
diff --git a/Magento2/Tests/Annotation/MethodAnnotationStructureUnitTest.inc b/Magento2/Tests/Annotation/MethodAnnotationStructureUnitTest.inc
index 6b7431c9..4ee0c4fa 100644
--- a/Magento2/Tests/Annotation/MethodAnnotationStructureUnitTest.inc
+++ b/Magento2/Tests/Annotation/MethodAnnotationStructureUnitTest.inc
@@ -373,7 +373,7 @@ class MethodAnnotationFixture
     /**
      * This deprecated function is correct even though it only contains the @deprecated tag.
      *
-     * @deprecated It will be removed in version 1.0.0
+     * @deprecated It will be removed in version 1.0.0 without replacement
      */
     public function correctBecauseOfKeywordPhrase()
     {
@@ -383,7 +383,7 @@ class MethodAnnotationFixture
     /**
      * This deprecated function is correct even though it only contains the @deprecated tag.
      *
-     * @deprecated WOW! It will be removed in version 1.0.0
+     * @deprecated WOW! It will be removed in version 1.0.0 without replacement
      */
     public function alsoCorrectBecauseOfKeywordPhrase()
     {
diff --git a/Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.1.inc b/Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.1.inc
index c9785e18..0dc9728b 100644
--- a/Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.1.inc
+++ b/Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.1.inc
@@ -164,7 +164,7 @@ class OldHandler
 }
 
 /**
- * @deprecated It will be removed in version 1.0.0
+ * @deprecated It will be removed in version 1.0.0 without replacement
  */
 class DeprecatedButHandler
 {
@@ -172,7 +172,7 @@ class DeprecatedButHandler
 }
 
 /**
- * @deprecated It's also deprecated, but it will be removed in version 1.0.0
+ * @deprecated It's also deprecated, but it will be removed in version 1.0.0 without replacement
  */
 class AlsoDeprecatedButHandler
 {
diff --git a/Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.2.inc b/Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.2.inc
index 62935860..c1c456ed 100644
--- a/Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.2.inc
+++ b/Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.2.inc
@@ -155,7 +155,7 @@ interface DoNotCareHandler
 }
 
 /**
- * @deprecated This interface will be removed in version 1.0.0
+ * @deprecated This interface will be removed in version 1.0.0 without replacement
  */
 interface DeprecatedButHandler
 {
@@ -163,7 +163,7 @@ interface DeprecatedButHandler
 }
 
 /**
- * @deprecated Yeah! This interface will be removed in version 1.0.0
+ * @deprecated Yeah! This interface will be removed in version 1.0.0 without replacement
  */
 interface AlsoDeprecatedButHandler
 {
diff --git a/Magento2/Tests/Commenting/ClassPropertyPHPDocFormattingUnitTest.inc b/Magento2/Tests/Commenting/ClassPropertyPHPDocFormattingUnitTest.inc
index 1c85b175..cde71269 100644
--- a/Magento2/Tests/Commenting/ClassPropertyPHPDocFormattingUnitTest.inc
+++ b/Magento2/Tests/Commenting/ClassPropertyPHPDocFormattingUnitTest.inc
@@ -197,7 +197,7 @@ class correctlyFormattedClassMemberDocBlock
 
     /**
      * @var string
-     * @deprecated This property will be removed in version 1.0.0
+     * @deprecated This property will be removed in version 1.0.0 without replacement
      */
     protected string $deprecatedWithKeyword;
 }
diff --git a/Magento2/Tests/Commenting/ConstantsPHPDocFormattingUnitTest.2.inc b/Magento2/Tests/Commenting/ConstantsPHPDocFormattingUnitTest.2.inc
index a75730e6..a751d8aa 100644
--- a/Magento2/Tests/Commenting/ConstantsPHPDocFormattingUnitTest.2.inc
+++ b/Magento2/Tests/Commenting/ConstantsPHPDocFormattingUnitTest.2.inc
@@ -65,12 +65,12 @@ class Profiler
     const d = 100;
 
     /**
-     * @deprecated This constant will be removed in version 1.0.0
+     * @deprecated This constant will be removed in version 1.0.0 without replacement
      */
     const KEYWORD_PHRASE = false;
 
     /**
-     * @deprecated It's awesome - This constant will be removed in version 1.0.0
+     * @deprecated It's awesome - This constant will be removed in version 1.0.0 without replacement
      */
     const WITH_KEYWORD_PHRASE = false;
 }

From 30bed9501a88b21f57eb80f0cc2b83496ef5eb1b Mon Sep 17 00:00:00 2001
From: Marc Ginesta <mginesta@adobe.com>
Date: Wed, 31 Aug 2022 18:03:37 +0200
Subject: [PATCH 3/5] Update condition for stripos

---
 Magento2/Helpers/Commenting/PHPDocFormattingValidator.php | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Magento2/Helpers/Commenting/PHPDocFormattingValidator.php b/Magento2/Helpers/Commenting/PHPDocFormattingValidator.php
index a5f33d8c..fc9dc419 100644
--- a/Magento2/Helpers/Commenting/PHPDocFormattingValidator.php
+++ b/Magento2/Helpers/Commenting/PHPDocFormattingValidator.php
@@ -126,8 +126,8 @@ public function hasDeprecatedWellFormatted($commentStartPtr, $tokens)
         }
         $seePtr = $this->getTagPosition('@see', $commentStartPtr, $tokens);
         if ($seePtr === -1) {
-            if (stripos($tokens[$deprecatedPtr + 2]['content'], self::REMOVED_IN_VERSION, 0) &&
-                stripos($tokens[$deprecatedPtr + 2]['content'], self::WITHOUT_REPLACEMENT, 0)) {
+            if (stripos($tokens[$deprecatedPtr + 2]['content'], self::REMOVED_IN_VERSION, 0) >= 0 &&
+                stripos($tokens[$deprecatedPtr + 2]['content'], self::WITHOUT_REPLACEMENT, 0) >= 0) {
                 return true;
             }
             return false;

From 180c5105e13e3323a738d1f205edf26652502f4a Mon Sep 17 00:00:00 2001
From: Marc Ginesta <mginesta@adobe.com>
Date: Wed, 31 Aug 2022 18:07:49 +0200
Subject: [PATCH 4/5] Update boolean comparison on condition

---
 Magento2/Helpers/Commenting/PHPDocFormattingValidator.php | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Magento2/Helpers/Commenting/PHPDocFormattingValidator.php b/Magento2/Helpers/Commenting/PHPDocFormattingValidator.php
index fc9dc419..c8761992 100644
--- a/Magento2/Helpers/Commenting/PHPDocFormattingValidator.php
+++ b/Magento2/Helpers/Commenting/PHPDocFormattingValidator.php
@@ -126,8 +126,8 @@ public function hasDeprecatedWellFormatted($commentStartPtr, $tokens)
         }
         $seePtr = $this->getTagPosition('@see', $commentStartPtr, $tokens);
         if ($seePtr === -1) {
-            if (stripos($tokens[$deprecatedPtr + 2]['content'], self::REMOVED_IN_VERSION, 0) >= 0 &&
-                stripos($tokens[$deprecatedPtr + 2]['content'], self::WITHOUT_REPLACEMENT, 0) >= 0) {
+            if (stripos($tokens[$deprecatedPtr + 2]['content'], self::REMOVED_IN_VERSION, 0) !== false &&
+                stripos($tokens[$deprecatedPtr + 2]['content'], self::WITHOUT_REPLACEMENT, 0) !== false) {
                 return true;
             }
             return false;

From 246c67bcf8d75985cad8effce3faa85a5143cae6 Mon Sep 17 00:00:00 2001
From: Marc Ginesta <mginesta@adobe.com>
Date: Thu, 1 Sep 2022 12:25:10 +0200
Subject: [PATCH 5/5] Refactor: Use preg_match

---
 .../Helpers/Commenting/PHPDocFormattingValidator.php     | 9 ++++-----
 .../Annotation/MethodAnnotationStructureUnitTest.inc     | 4 ++--
 .../ClassAndInterfacePHPDocFormattingUnitTest.1.inc      | 4 ++--
 3 files changed, 8 insertions(+), 9 deletions(-)

diff --git a/Magento2/Helpers/Commenting/PHPDocFormattingValidator.php b/Magento2/Helpers/Commenting/PHPDocFormattingValidator.php
index c8761992..a87312d5 100644
--- a/Magento2/Helpers/Commenting/PHPDocFormattingValidator.php
+++ b/Magento2/Helpers/Commenting/PHPDocFormattingValidator.php
@@ -13,9 +13,6 @@
  */
 class PHPDocFormattingValidator
 {
-    private const REMOVED_IN_VERSION = 'removed in version';
-    private const WITHOUT_REPLACEMENT = 'without replacement';
-
     /**
      * Finds matching PHPDoc for current pointer
      *
@@ -126,8 +123,10 @@ public function hasDeprecatedWellFormatted($commentStartPtr, $tokens)
         }
         $seePtr = $this->getTagPosition('@see', $commentStartPtr, $tokens);
         if ($seePtr === -1) {
-            if (stripos($tokens[$deprecatedPtr + 2]['content'], self::REMOVED_IN_VERSION, 0) !== false &&
-                stripos($tokens[$deprecatedPtr + 2]['content'], self::WITHOUT_REPLACEMENT, 0) !== false) {
+            if (preg_match(
+                "/This [a-zA-Z]* will be removed in version \d.\d.\d without replacement/",
+                $tokens[$deprecatedPtr + 2]['content']
+            )) {
                 return true;
             }
             return false;
diff --git a/Magento2/Tests/Annotation/MethodAnnotationStructureUnitTest.inc b/Magento2/Tests/Annotation/MethodAnnotationStructureUnitTest.inc
index 4ee0c4fa..2e0fdf0e 100644
--- a/Magento2/Tests/Annotation/MethodAnnotationStructureUnitTest.inc
+++ b/Magento2/Tests/Annotation/MethodAnnotationStructureUnitTest.inc
@@ -373,7 +373,7 @@ class MethodAnnotationFixture
     /**
      * This deprecated function is correct even though it only contains the @deprecated tag.
      *
-     * @deprecated It will be removed in version 1.0.0 without replacement
+     * @deprecated This method will be removed in version 1.0.0 without replacement
      */
     public function correctBecauseOfKeywordPhrase()
     {
@@ -383,7 +383,7 @@ class MethodAnnotationFixture
     /**
      * This deprecated function is correct even though it only contains the @deprecated tag.
      *
-     * @deprecated WOW! It will be removed in version 1.0.0 without replacement
+     * @deprecated WOW! This method will be removed in version 1.0.0 without replacement
      */
     public function alsoCorrectBecauseOfKeywordPhrase()
     {
diff --git a/Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.1.inc b/Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.1.inc
index 0dc9728b..afd4c934 100644
--- a/Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.1.inc
+++ b/Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.1.inc
@@ -164,7 +164,7 @@ class OldHandler
 }
 
 /**
- * @deprecated It will be removed in version 1.0.0 without replacement
+ * @deprecated This class will be removed in version 1.0.0 without replacement
  */
 class DeprecatedButHandler
 {
@@ -172,7 +172,7 @@ class DeprecatedButHandler
 }
 
 /**
- * @deprecated It's also deprecated, but it will be removed in version 1.0.0 without replacement
+ * @deprecated It's also deprecated - This class will be removed in version 1.0.0 without replacement
  */
 class AlsoDeprecatedButHandler
 {