Merge pull request #180 from magento-commerce/imported-loginesta-magento-coding-standard-397

[Imported] AC-3100: Add the @deprecated and @see tag check to ClassPropertyPHPDocFormattingSniff

Author: loginesta

Magento2/Sniffs/Commenting/ClassPropertyPHPDocFormattingSniff.php

@@ -67,6 +67,15 @@ public function processMemberVar(File $phpcsFile, $stackPtr)
         }
 
         $commentStart = $tokens[$commentEnd]['comment_opener'];
+        if ($this->PHPDocFormattingValidator->hasDeprecatedWellFormatted($commentStart, $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.',
+                $stackPtr,
+                'InvalidDeprecatedTagUsage'
+            );
+        }
         $varAnnotationPosition = null;
         foreach ($tokens[$commentStart]['comment_tags'] as $tag) {
             if ($tokens[$tag]['content'] === '@var') {

Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.php

@@ -35,7 +35,7 @@ public function getWarningList($testFile = '')
             101 => 1,
             109 => 1,
             118 => 1,
-            127 => 1,
+            127 => 1
         ];
     }
 }

Magento2/Tests/Commenting/ClassPropertyPHPDocFormattingUnitTest.inc

@@ -142,4 +142,56 @@ class correctlyFormattedClassMemberDocBlock
      * @var string|null
      */
     protected ?string $test2;
+
+    /**
+     * @var string
+     * @deprecated
+     */
+    protected string $badlyDeprecated;
+
+    /**
+     * @var string
+     * @deprecated Why not
+     */
+    protected string $incorrectlyDeprecated;
+
+    /**
+     * @var string
+     * @deprecated
+     * @see
+     */
+    protected string $inaccurately;
+
+    /**
+     * @var string
+     * @deprecated No reference specified
+     * @see
+     */
+    protected string $mistakenly;
+
+    /**
+     * @var string
+     * @deprecated No reference specified
+     * @see Some reference
+     */
+    protected string $correctly;
+
+    /**
+     * @var string
+     * @deprecated
+     * @see Some other reference
+     */
+    protected string $alsoCorrect;
+
+    /**
+     * @var string
+     * @see
+     */
+    protected string $shouldBeCorrect;
+
+    /**
+     * @var string
+     * @see Message with some reference
+     */
+    protected string $itIsCorrect;
 }

Magento2/Tests/Commenting/ClassPropertyPHPDocFormattingUnitTest.php

@@ -34,7 +34,11 @@ public function getWarningList()
             63 => 1,
             68 => 1,
             75 => 1,
-            125 => 1
+            125 => 1,
+            150 => 1,
+            156 => 1,
+            163 => 1,
+            170 => 1
         ];
     }
 }