From ae9ae1050a23f965b0376a4bbc931e11876bbfe5 Mon Sep 17 00:00:00 2001
From: Craig Newbury <craig@newbury.me>
Date: Mon, 17 May 2021 15:13:18 +0100
Subject: [PATCH 1/3] Updated sniff to allow automatic fixing

---
 ...ClassAndInterfacePHPDocFormattingSniff.php | 56 +++++++++++++++++--
 1 file changed, 51 insertions(+), 5 deletions(-)

diff --git a/Magento2/Sniffs/Commenting/ClassAndInterfacePHPDocFormattingSniff.php b/Magento2/Sniffs/Commenting/ClassAndInterfacePHPDocFormattingSniff.php
index 48426a1a..59285a18 100644
--- a/Magento2/Sniffs/Commenting/ClassAndInterfacePHPDocFormattingSniff.php
+++ b/Magento2/Sniffs/Commenting/ClassAndInterfacePHPDocFormattingSniff.php
@@ -63,7 +63,7 @@ public function process(File $phpcsFile, $stackPtr)
         }
 
         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,13 +71,32 @@ public function process(File $phpcsFile, $stackPtr)
                 $stackPtr,
                 'InvalidDescription'
             );
+            if ($fix === true) {
+                $phpcsFile->fixer->beginChangeset();
+                $startPtr = false;
+                $endPtr = false;
+                $searchPtr = $stackPtr;
+                while (!$startPtr || !$endPtr) {
+                    $searchPtr--;
+                    if ($tokens[$searchPtr]['code'] === T_DOC_COMMENT_OPEN_TAG) {
+                        $startPtr = $searchPtr;
+                    }
+                    if ($tokens[$searchPtr]['code'] === T_DOC_COMMENT_CLOSE_TAG) {
+                        $endPtr = $searchPtr;
+                    }
+                }
+                for ($removing = $startPtr; $removing <= $endPtr; $removing++) {
+                    $phpcsFile->fixer->replaceToken($removing, '');
+                }
+                $phpcsFile->fixer->endChangeset();
+            }
         }
 
         if ($this->PHPDocFormattingValidator->hasDeprecatedWellFormatted($commentStartPtr, $tokens) !== true) {
             $phpcsFile->addWarning(
                 'Motivation behind the added @deprecated tag MUST be explained. '
-                    . '@see tag MUST be used with reference to new implementation when code is deprecated '
-                    . 'and there is a new alternative.',
+                . '@see tag MUST be used with reference to new implementation when code is deprecated '
+                . 'and there is a new alternative.',
                 $stackPtr,
                 'InvalidDeprecatedTagUsage'
             );
@@ -104,14 +123,41 @@ 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 === true) {
+                    $phpcsFile->fixer->beginChangeset();
+                    $startOfLineToken = $i - 3;
+                    $endOfLineToken = $i + 3;
+
+                    $startFound = false;
+                    $startPtr = $i;
+                    while (!$startFound) {
+                        $startPtr--;
+                        if ($tokens[$startPtr]['code'] === T_DOC_COMMENT_WHITESPACE && $tokens[$startPtr]['content'] === "\n") {
+                            $startFound = true;
+                        }
+                    }
+                    $endFound = false;
+                    $endPtr = $i;
+                    while (!$endFound) {
+                        $endPtr++;
+                        if ($tokens[$endPtr]['code'] === T_DOC_COMMENT_WHITESPACE && $tokens[$endPtr]['content'] === "\n") {
+                            $endFound = true;
+                            $endPtr--;
+                        }
+                    }
+
+                    for ($removing = $startOfLineToken; $removing <= $endOfLineToken; $removing++) {
+                        $phpcsFile->fixer->replaceToken($removing, '');
+                    }
+                    $phpcsFile->fixer->endChangeset();
+                }
             }
         }
-
         return false;
     }
 }

From 524194c23cb945ce08e6e9640285a3a0593e66c7 Mon Sep 17 00:00:00 2001
From: Craig Newbury <craig@newbury.me>
Date: Mon, 17 May 2021 15:29:34 +0100
Subject: [PATCH 2/3] Fix line length

---
 .../Commenting/ClassAndInterfacePHPDocFormattingSniff.php   | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/Magento2/Sniffs/Commenting/ClassAndInterfacePHPDocFormattingSniff.php b/Magento2/Sniffs/Commenting/ClassAndInterfacePHPDocFormattingSniff.php
index 59285a18..b12887fd 100644
--- a/Magento2/Sniffs/Commenting/ClassAndInterfacePHPDocFormattingSniff.php
+++ b/Magento2/Sniffs/Commenting/ClassAndInterfacePHPDocFormattingSniff.php
@@ -137,7 +137,8 @@ private function validateTags(File $phpcsFile, $commentStartPtr, $tokens)
                     $startPtr = $i;
                     while (!$startFound) {
                         $startPtr--;
-                        if ($tokens[$startPtr]['code'] === T_DOC_COMMENT_WHITESPACE && $tokens[$startPtr]['content'] === "\n") {
+                        $token = $tokens[$startPtr];
+                        if ($token['code'] === T_DOC_COMMENT_WHITESPACE && $token['content'] === "\n") {
                             $startFound = true;
                         }
                     }
@@ -145,7 +146,8 @@ private function validateTags(File $phpcsFile, $commentStartPtr, $tokens)
                     $endPtr = $i;
                     while (!$endFound) {
                         $endPtr++;
-                        if ($tokens[$endPtr]['code'] === T_DOC_COMMENT_WHITESPACE && $tokens[$endPtr]['content'] === "\n") {
+                        $token = $tokens[$startPtr];
+                        if ($token['code'] === T_DOC_COMMENT_WHITESPACE && $token['content'] === "\n") {
                             $endFound = true;
                             $endPtr--;
                         }

From 23a107a2a3b8680287a261d8df3ae2f5ec2c62a5 Mon Sep 17 00:00:00 2001
From: Craig Newbury <craig@gene.co.uk>
Date: Mon, 4 Oct 2021 23:54:00 +0100
Subject: [PATCH 3/3] Added fixer test file

---
 ...erfacePHPDocFormattingUnitTest.1.inc.fixed | 152 ++++++++++++++++++
 1 file changed, 152 insertions(+)
 create mode 100644 Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.1.inc.fixed

diff --git a/Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.1.inc.fixed b/Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.1.inc.fixed
new file mode 100644
index 00000000..0698dfbc
--- /dev/null
+++ b/Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.1.inc.fixed
@@ -0,0 +1,152 @@
+<?php
+
+/**
+ * Handler for PHP errors/warnings/notices that converts them to exceptions.
+ */
+class ErrorHandler
+{
+
+}
+
+class NotAnErrorHandler
+{
+
+}
+
+
+class FaultyHandler
+{
+
+}
+
+
+class SomeHandler
+{
+
+}
+
+
+class YetAnotherHandler
+{
+
+}
+
+/**
+ * @api Do not confuse tag for faulty short description
+ */
+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
+{
+
+}