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.

Author: fredden

Magento2/Sniffs/Commenting/ClassAndInterfacePHPDocFormattingSniff.php

@@ -62,15 +62,29 @@ 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'])
                 ),
                 $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;
+                        }
+                    }
+                }
             }
         }
 

Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.1.inc

@@ -179,3 +179,10 @@ class AlsoDeprecatedButHandler
 
 }
 
+/**
+ * @package this tag should not be used
+ */
+class OnlyUselessCommentContent
+{
+
+}

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

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