Merge pull request #179 from magento-commerce/imported-loginesta-magento-coding-standard-396

[Imported] AC-3099: Add a sniff for functions to display a warning when there is no @see tag

Author: loginesta

Magento2/Sniffs/Annotation/MethodAnnotationStructureSniff.php

@@ -7,6 +7,7 @@
 
 namespace Magento2\Sniffs\Annotation;
 
+use Magento2\Helpers\Commenting\PHPDocFormattingValidator;
 use PHP_CodeSniffer\Files\File;
 use PHP_CodeSniffer\Sniffs\Sniff;
 
@@ -20,12 +21,18 @@ class MethodAnnotationStructureSniff implements Sniff
      */
     private $annotationFormatValidator;
 
+    /**
+     * @var PHPDocFormattingValidator
+     */
+    private $PHPDocFormattingValidator;
+
     /**
      * AnnotationStructureSniff constructor.
      */
     public function __construct()
     {
         $this->annotationFormatValidator = new AnnotationFormatValidator();
+        $this->PHPDocFormattingValidator = new PHPDocFormattingValidator();
     }
 
     /**
@@ -45,6 +52,16 @@ public function process(File $phpcsFile, $stackPtr)
     {
         $tokens = $phpcsFile->getTokens();
         $commentStartPtr = $phpcsFile->findPrevious(T_DOC_COMMENT_OPEN_TAG, ($stackPtr), 0);
+
+        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.',
+                $stackPtr,
+                'InvalidDeprecatedTagUsage'
+            );
+        }
         $commentEndPtr = $phpcsFile->findPrevious(T_DOC_COMMENT_CLOSE_TAG, ($stackPtr), 0);
         if (!$commentStartPtr) {
             $phpcsFile->addError('Comment block is missing', $stackPtr, 'MethodArguments');

Magento2/Tests/Annotation/MethodAnnotationStructureUnitTest.inc

@@ -306,4 +306,67 @@ class MethodAnnotationFixture
     {
         return $start === $length;
     }
+
+    /**
+     * This is a well-formed deprecated function
+     *
+     * @deprecated can be used in this context
+     * @see is ok here
+     */
+    public function deprecated(): bool
+    {
+        return true;
+    }
+
+    /**
+     * This deprecated function is incorrect since it only contains the @deprecated tag
+     *
+     * @deprecated
+     */
+    public function incorrectlyDeprecated()
+    {
+        return false;
+    }
+
+    /**
+     * This deprecated function is incorrect since it only contains the @deprecated tag
+     *
+     * @deprecated Should not be used
+     */
+    public function incorrectAsWell()
+    {
+        return false;
+    }
+
+    /**
+     * This deprecated function is incorrect since the @see tag does not have extra info
+     *
+     * @deprecated
+     * @see
+     */
+    public function anotherOne()
+    {
+        return false;
+    }
+
+    /**
+     * This deprecated function is incorrect since the @see tag does not have extra info
+     *
+     * @deprecated Should not be used
+     * @see
+     */
+    public function yetAnotherOne()
+    {
+        return false;
+    }
+
+    /**
+     * This function is correct since the @see tag can be used without the @deprecated tag
+     *
+     * @see Magento\Framework\NewHandler
+     */
+    public function correctUseOfSee()
+    {
+        return true;
+    }
 }

Magento2/Tests/Annotation/MethodAnnotationStructureUnitTest.php

@@ -46,6 +46,11 @@ public function getErrorList()
      */
     public function getWarningList()
     {
-        return [];
+        return [
+            326 => 1,
+            336 => 1,
+            347 => 1,
+            358 => 1
+        ];
     }
 }