Updated sniff to allow automatic fixing

Magento2/Sniffs/Commenting/ClassAndInterfacePHPDocFormattingSniff.php

@@ -63,21 +63,40 @@ 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'])
                 ),
                 $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,43 @@ 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--;
+                        $token = $tokens[$startPtr];
+                        if ($token['code'] === T_DOC_COMMENT_WHITESPACE && $token['content'] === "\n") {
+                            $startFound = true;
+                        }
+                    }
+                    $endFound = false;
+                    $endPtr = $i;
+                    while (!$endFound) {
+                        $endPtr++;
+                        $token = $tokens[$startPtr];
+                        if ($token['code'] === T_DOC_COMMENT_WHITESPACE && $token['content'] === "\n") {
+                            $endFound = true;
+                            $endPtr--;
+                        }
+                    }
+
+                    for ($removing = $startOfLineToken; $removing <= $endOfLineToken; $removing++) {
+                        $phpcsFile->fixer->replaceToken($removing, '');
+                    }
+                    $phpcsFile->fixer->endChangeset();
+                }
             }
         }
-
         return false;
     }
 }

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
+{
+
+}