From 5936239050ddb99f5aea5c9ab655efbc1e6c2c35 Mon Sep 17 00:00:00 2001
From: Dan Wallis <mrdanwallis@gmail.com>
Date: Thu, 26 Jan 2023 11:51:03 +0000
Subject: [PATCH] Automatically remove useless comments

When issues are detected and classified as
Magento2.Commenting.ClassAndInterfacePHPDocFormatting.ForbiddenTags or
Magento2.Commenting.ClassAndInterfacePHPDocFormatting.InvalidDescription,
these can be fixed by removing the offending comment.
---
 ...ClassAndInterfacePHPDocFormattingSniff.php |  42 ++++-
 ...AndInterfacePHPDocFormattingUnitTest.1.inc |   7 +
 ...erfacePHPDocFormattingUnitTest.1.inc.fixed | 166 ++++++++++++++++++
 ...AndInterfacePHPDocFormattingUnitTest.2.inc |  17 ++
 ...erfacePHPDocFormattingUnitTest.2.inc.fixed | 166 ++++++++++++++++++
 ...ssAndInterfacePHPDocFormattingUnitTest.php |   3 +-
 6 files changed, 398 insertions(+), 3 deletions(-)
 create mode 100644 Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.1.inc.fixed
 create mode 100644 Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.2.inc.fixed

diff --git a/Magento2/Sniffs/Commenting/ClassAndInterfacePHPDocFormattingSniff.php b/Magento2/Sniffs/Commenting/ClassAndInterfacePHPDocFormattingSniff.php
index 2d715c50..fec9f396 100644
--- a/Magento2/Sniffs/Commenting/ClassAndInterfacePHPDocFormattingSniff.php
+++ b/Magento2/Sniffs/Commenting/ClassAndInterfacePHPDocFormattingSniff.php
@@ -62,8 +62,10 @@ public function process(File $phpcsFile, $stackPtr)
             return;
         }
 
+        $commentCloserPtr = $tokens[$commentStartPtr]['comment_closer'];
+
         if ($this->PHPDocFormattingValidator->providesMeaning($namePtr, $commentStartPtr, $tokens) !== true) {
-            $phpcsFile->addWarning(
+            $fix = $phpcsFile->addFixableWarning(
                 sprintf(
                     '%s description must contain meaningful information beyond what its name provides or be removed.',
                     ucfirst($tokens[$stackPtr]['content'])
@@ -71,6 +73,18 @@ public function process(File $phpcsFile, $stackPtr)
                 $stackPtr,
                 'InvalidDescription'
             );
+
+            if ($fix) {
+                for ($i = $commentStartPtr; $i <= $commentCloserPtr; $i++) {
+                    $phpcsFile->fixer->replaceToken($i, '');
+                }
+
+                if ($tokens[$commentStartPtr - 1]['code'] === T_WHITESPACE
+                    && $tokens[$commentCloserPtr + 1]['code'] === T_WHITESPACE
+                ) {
+                    $phpcsFile->fixer->replaceToken($commentCloserPtr + 1, '');
+                }
+            }
         }
 
         if ($this->PHPDocFormattingValidator->hasDeprecatedWellFormatted($commentStartPtr, $tokens) !== true) {
@@ -104,11 +118,35 @@ private function validateTags(File $phpcsFile, $commentStartPtr, $tokens)
             }
 
             if (in_array($tokens[$i]['content'], $this->forbiddenTags) === true) {
-                $phpcsFile->addWarning(
+                $fix = $phpcsFile->addFixableWarning(
                     sprintf('Tag %s MUST NOT be used.', $tokens[$i]['content']),
                     $i,
                     'ForbiddenTags'
                 );
+
+                if ($fix) {
+                    for ($j = $i - 1; $j > $commentStartPtr; $j--) {
+                        if (!in_array($tokens[$j]['code'], [T_DOC_COMMENT_STAR, T_DOC_COMMENT_WHITESPACE], true)) {
+                            break;
+                        }
+
+                        if ($tokens[$j]['code'] === T_DOC_COMMENT_WHITESPACE && $tokens[$j]['content'] === "\n") {
+                            break;
+                        }
+
+                        $phpcsFile->fixer->replaceToken($j, '');
+                    }
+
+                    $phpcsFile->fixer->replaceToken($i, '');
+
+                    for ($j = $i + 1; $j < $commentCloserPtr; $j++) {
+                        $phpcsFile->fixer->replaceToken($j, '');
+
+                        if ($tokens[$j]['code'] === T_DOC_COMMENT_WHITESPACE && $tokens[$j]['content'] === "\n") {
+                            break;
+                        }
+                    }
+                }
             }
         }
 
diff --git a/Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.1.inc b/Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.1.inc
index afd4c934..a17e80c8 100644
--- a/Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.1.inc
+++ b/Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.1.inc
@@ -179,3 +179,10 @@ class AlsoDeprecatedButHandler
 
 }
 
+/**
+ * @package this tag should not be used
+ */
+class OnlyUselessCommentContent
+{
+
+}
diff --git a/Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.1.inc.fixed b/Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.1.inc.fixed
new file mode 100644
index 00000000..6be0195c
--- /dev/null
+++ b/Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.1.inc.fixed
@@ -0,0 +1,166 @@
+<?php
+
+/**
+ * Handler for PHP errors/warnings/notices that converts them to exceptions.
+ */
+class ErrorHandler
+{
+
+}
+
+class NotAnErrorHandler
+{
+
+}
+
+class FaultyHandler
+{
+
+}
+
+class SomeHandler
+{
+
+}
+
+class YetAnotherHandler
+{
+
+}
+
+class GreenHandler
+{
+
+}
+
+class EmptyHandler
+{
+
+}
+
+/**
+ * Handler for PHP errors/warnings/notices that converts them to exceptions.
+ *
+ * @api is ok here
+ * @deprecated can be used in this context
+ * @see is ok here
+ * @author is actually ok
+ */
+class ExampleHandler
+{
+
+}
+
+/**
+ * @api
+ * @since 100.0.2
+ */
+class ApiHandler
+{
+
+}
+
+/**
+ * @api
+ */
+class AsyncApiHandler
+{
+
+}
+
+/**
+ * @SuppressWarnings(PHPMD.CouplingBetweenObjects)
+ */
+class GroupRepositoryHandler
+{
+
+}
+
+/**
+ * @deprecated
+ */
+class DeprecatedHandler
+{
+
+}
+
+/**
+ * @deprecated Should not be used
+ */
+class AncientHandler
+{
+
+}
+
+/**
+ * @deprecated
+ * @see
+ */
+class AgedHandler
+{
+
+}
+
+/**
+ * @deprecated Should not be used
+ * @see
+ */
+class ArhaicHandler
+{
+
+}
+
+/**
+ * @deprecated Should not be used
+ * @see Magento\Framework\NewHandler
+ */
+class OldHandler
+{
+
+}
+
+/**
+ * @see Magento\Framework\NewHandler
+ */
+class SomethingHandler
+{
+
+}
+
+/**
+ * @see
+ */
+class DoNotCareHandler
+{
+
+}
+
+/**
+ * @deprecated
+ * @see Magento\Framework\NewHandler
+ */
+class OldHandler
+{
+
+}
+
+/**
+ * @deprecated This class will be removed in version 1.0.0 without replacement
+ */
+class DeprecatedButHandler
+{
+
+}
+
+/**
+ * @deprecated It's also deprecated - This class will be removed in version 1.0.0 without replacement
+ */
+class AlsoDeprecatedButHandler
+{
+
+}
+
+class OnlyUselessCommentContent
+{
+
+}
diff --git a/Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.2.inc b/Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.2.inc
index c1c456ed..d6e4be63 100644
--- a/Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.2.inc
+++ b/Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.2.inc
@@ -154,6 +154,15 @@ interface DoNotCareHandler
 
 }
 
+/**
+ * @deprecated
+ * @see Magento\Framework\NewHandler
+ */
+interface OldHandler
+{
+
+}
+
 /**
  * @deprecated This interface will be removed in version 1.0.0 without replacement
  */
@@ -169,3 +178,11 @@ interface AlsoDeprecatedButHandler
 {
 
 }
+
+/**
+ * @package this tag should not be used
+ */
+interface OnlyUselessCommentContent
+{
+
+}
diff --git a/Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.2.inc.fixed b/Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.2.inc.fixed
new file mode 100644
index 00000000..9c90de04
--- /dev/null
+++ b/Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.2.inc.fixed
@@ -0,0 +1,166 @@
+<?php
+
+/**
+ * Handler for PHP errors/warnings/notices that converts them to exceptions.
+ */
+interface ErrorHandler
+{
+
+}
+
+interface NotAnErrorHandler
+{
+
+}
+
+interface FaultyHandler
+{
+
+}
+
+interface SomeHandler
+{
+
+}
+
+interface YetAnotherHandler
+{
+
+}
+
+interface GreenHandler
+{
+
+}
+
+interface EmptyHandler
+{
+
+}
+
+/**
+ * Handler for PHP errors/warnings/notices that converts them to exceptions.
+ *
+ * @api is ok here
+ * @deprecated can be used in this context
+ * @see is ok here
+ * @author is actually ok
+ */
+interface ExampleHandler
+{
+
+}
+
+/**
+ * @api
+ * @since 100.0.2
+ */
+interface ApiHandler
+{
+
+}
+
+/**
+ * @api
+ */
+interface AsyncApiHandler
+{
+
+}
+
+/**
+ * @SuppressWarnings(PHPMD.CouplingBetweenObjects)
+ */
+interface GroupRepositoryHandler
+{
+
+}
+
+/**
+ * @deprecated
+ */
+interface DeprecatedHandler
+{
+
+}
+
+/**
+ * @deprecated Should not be used
+ */
+interface AncientHandler
+{
+
+}
+
+/**
+ * @deprecated
+ * @see
+ */
+interface AgedHandler
+{
+
+}
+
+/**
+ * @deprecated Should not be used
+ * @see
+ */
+interface ArhaicHandler
+{
+
+}
+
+/**
+ * @deprecated Should not be used
+ * @see Magento\Framework\NewHandler
+ */
+interface OldHandler
+{
+
+}
+
+/**
+ * @see Magento\Framework\NewHandler
+ */
+interface SomethingHandler
+{
+
+}
+
+/**
+ * @see
+ */
+interface DoNotCareHandler
+{
+
+}
+
+/**
+ * @deprecated
+ * @see Magento\Framework\NewHandler
+ */
+interface OldHandler
+{
+
+}
+
+/**
+ * @deprecated This interface will be removed in version 1.0.0 without replacement
+ */
+interface DeprecatedButHandler
+{
+
+}
+
+/**
+ * @deprecated Yeah! This interface will be removed in version 1.0.0 without replacement
+ */
+interface AlsoDeprecatedButHandler
+{
+
+}
+
+interface OnlyUselessCommentContent
+{
+
+}
diff --git a/Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.php b/Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.php
index 868187c3..8ef3e860 100644
--- a/Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.php
+++ b/Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.php
@@ -35,7 +35,8 @@ public function getWarningList($testFile = '')
             101 => 1,
             109 => 1,
             118 => 1,
-            127 => 1
+            127 => 1,
+            183 => 1,
         ];
     }
 }