Implement rule from #105

Magento2/Sniffs/Commenting/ClassAndInterfacePHPDocFormattingSniff.php

@@ -0,0 +1,121 @@
+<?php
+
+/**
+ * Copyright © Magento. All rights reserved.
+ * See COPYING.txt for license details.
+ */
+namespace Magento2\Sniffs\Commenting;
+
+use PHP_CodeSniffer\Sniffs\Sniff;
+use PHP_CodeSniffer\Files\File;
+
+/**
+ * Detects PHPDoc formatting for classes and interfaces.
+ */
+class ClassAndInterfacePHPDocFormattingSniff implements Sniff
+{
+    /**
+     * @var PHPDocFormattingValidator
+     */
+    private $PHPDocFormattingValidator;
+
+    /**
+     * @var string[] List of tags that can not be used in comments
+     */
+    public $forbiddenTags = [
+        '@category',
+        '@package',
+        '@subpackage'
+    ];
+
+    /**
+     * Helper initialisation
+     */
+    public function __construct()
+    {
+        $this->PHPDocFormattingValidator = new PHPDocFormattingValidator();
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function register()
+    {
+        return [
+            T_CLASS,
+            T_INTERFACE
+        ];
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function process(File $phpcsFile, $stackPtr)
+    {
+        $tokens = $phpcsFile->getTokens();
+
+        $namePtr = $phpcsFile->findNext(T_STRING, $stackPtr + 1, null, false, null, true);
+
+        $commentStartPtr = $phpcsFile->findPrevious(
+            [
+                T_WHITESPACE,
+                T_DOC_COMMENT_STAR,
+                T_DOC_COMMENT_WHITESPACE,
+                T_DOC_COMMENT_TAG,
+                T_DOC_COMMENT_STRING,
+                T_DOC_COMMENT_CLOSE_TAG
+            ],
+            $stackPtr - 1,
+            null,
+            true,
+            null,
+            true
+        );
+
+        if ($tokens[$commentStartPtr]['code'] !== T_DOC_COMMENT_OPEN_TAG) {
+            return;
+        }
+
+        if ($this->PHPDocFormattingValidator->providesMeaning($namePtr, $commentStartPtr, $tokens) !== true) {
+            $phpcsFile->addWarning(
+                sprintf(
+                    '%s description should contain additional information beyond the name already supplies.',
+                    ucfirst($tokens[$stackPtr]['content'])
+                ),
+                $stackPtr,
+                'InvalidDescription'
+            );
+        }
+
+        $this->validateTags($phpcsFile, $commentStartPtr, $tokens);
+    }
+
+    /**
+     * Validates that forbidden tags are not used in comment
+     *
+     * @param File $phpcsFile
+     * @param int $commentStartPtr
+     * @param array $tokens
+     * @return bool
+     */
+    private function validateTags(File $phpcsFile, $commentStartPtr, $tokens)
+    {
+        $commentCloserPtr = $tokens[$commentStartPtr]['comment_closer'];
+
+        for ($i = $commentStartPtr; $i <= $commentCloserPtr; $i++) {
+            if ($tokens[$i]['code'] !== T_DOC_COMMENT_TAG) {
+                continue;
+            }
+
+            if (in_array($tokens[$i]['content'], $this->forbiddenTags) === true) {
+                $phpcsFile->addWarning(
+                    sprintf('Tag %s MUST NOT be used.', $tokens[$i]['content']),
+                    $i,
+                    'ForbiddenTags'
+                );
+            }
+        }
+
+        return false;
+    }
+}

Magento2/Sniffs/Commenting/ConstantsPHPDocFormattingSniff.php

@@ -13,6 +13,19 @@
  */
 class ConstantsPHPDocFormattingSniff implements Sniff
 {
+    /**
+     * @var PHPDocFormattingValidator
+     */
+    private $PHPDocFormattingValidator;
+
+    /**
+     * Helper initialisation
+     */
+    public function __construct()
+    {
+        $this->PHPDocFormattingValidator = new PHPDocFormattingValidator();
+    }
+
     /**
      * @inheritDoc
      */
@@ -45,42 +58,18 @@ public function process(File $phpcsFile, $stackPtr)
             null,
             true
         );
-        $constName = strtolower(trim($tokens[$constNamePtr]['content'], " '\""));
 
         $commentStartPtr = $phpcsFile->findPrevious(T_DOC_COMMENT_OPEN_TAG, $stackPtr - 1, null, false, null, true);
         if ($commentStartPtr === false) {
             return;
         }
 
-        $commentCloserPtr = $tokens[$commentStartPtr]['comment_closer'];
-        for ($i = $commentStartPtr; $i <= $commentCloserPtr; $i++) {
-            $token = $tokens[$i];
-
-            // Not an interesting string
-            if ($token['code'] !== T_DOC_COMMENT_STRING) {
-                continue;
-            }
-
-            // Comment is the same as constant name
-            $docComment = trim(strtolower($token['content']), ',.');
-            if ($docComment === $constName) {
-                continue;
-            }
-
-            // Comment is exactly the same as constant name
-            $docComment = str_replace(' ', '_', $docComment);
-            if ($docComment === $constName) {
-                continue;
-            }
-
-            // We have found at lease one meaningful line in comment description
-            return;
+        if ($this->PHPDocFormattingValidator->providesMeaning($constNamePtr, $commentStartPtr, $tokens) !== true) {
+            $phpcsFile->addWarning(
+                'Constants must have short description if they add information beyond what the constant name supplies.',
+                $stackPtr,
+                'MissingConstantPHPDoc'
+            );
         }
-
-        $phpcsFile->addWarning(
-            'Constants must have short description if they add information beyond what the constant name supplies.',
-            $stackPtr,
-            'MissingConstantPHPDoc'
-        );
     }
 }

Magento2/Sniffs/Commenting/PHPDocFormattingValidator.php

@@ -0,0 +1,74 @@
+<?php
+
+/**
+ * Copyright © Magento. All rights reserved.
+ * See COPYING.txt for license details.
+ */
+namespace Magento2\Sniffs\Commenting;
+
+/**
+ * Helper class for common DocBlock validations
+ */
+class PHPDocFormattingValidator
+{
+    /**
+     * Determines if the comment identified by $commentStartPtr provides additional meaning to origin at $namePtr
+     *
+     * @param int $namePtr
+     * @param int $commentStartPtr
+     * @param array $tokens
+     * @return bool
+     */
+    public function providesMeaning($namePtr, $commentStartPtr, $tokens)
+    {
+        $commentCloserPtr = $tokens[$commentStartPtr]['comment_closer'];
+        $name = strtolower(str_replace([' ', '"', '_'], '', $tokens[$namePtr]['content']));
+
+        $hasTags = false;
+        $hasDescription = false;
+
+        for ($i = $commentStartPtr; $i <= $commentCloserPtr; $i++) {
+            $token = $tokens[$i];
+
+            // Important, but not the string we are looking for
+            if ($token['code'] === T_DOC_COMMENT_TAG) {
+                $hasTags = true;
+                continue;
+            }
+
+            // Not an interesting string
+            if ($token['code'] !== T_DOC_COMMENT_STRING) {
+                continue;
+            }
+
+            // Wrong kind of string
+            if ($tokens[$i - 2]['code'] === T_DOC_COMMENT_TAG) {
+                continue;
+            }
+
+            $hasDescription = true;
+
+            // Comment is the same as the origin name
+            $docComment = str_replace(['_', ' ', '.', ','], '', strtolower($token['content']));
+            if ($docComment === $name) {
+                continue;
+            }
+
+            // Only difference is word Class or Interface
+            $docComment = str_replace(['class', 'interface'], '', $docComment);
+            if ($docComment === $name) {
+                continue;
+            }
+
+            // We have found at lease one meaningful line in comment description
+            return true;
+        }
+
+        // Contains nothing but the tags
+        if ($hasTags === true && $hasDescription === false) {
+            return true;
+        }
+
+        return false;
+    }
+}

Magento2/Tests/CodeAnalysis/EmptyBlockUnitTest.php

@@ -7,9 +7,6 @@
 
 use PHP_CodeSniffer\Tests\Standards\AbstractSniffUnitTest;
 
-/**
- * Class EmptyBlockUnitTest
- */
 class EmptyBlockUnitTest extends AbstractSniffUnitTest
 {
     /**

Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.1.inc

@@ -0,0 +1,93 @@
+<?php
+
+/**
+ * Handler for PHP errors/warnings/notices that converts them to exceptions.
+ */
+class ErrorHandler
+{
+
+}
+
+class NotAnErrorHandler
+{
+
+}
+
+/**
+ * Faulty Handler
+ */
+class FaultyHandler
+{
+
+}
+
+/**
+ * Class SomeHandler
+ */
+class SomeHandler
+{
+
+}
+
+/**
+ * YetAnotherHandler
+ */
+class YetAnotherHandler
+{
+
+}
+
+/**
+ * GreenHandler
+ * @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
+ * @author is actually ok
+ * @category is irrelevant
+ * @package is not ment to be used
+ * @subpackage does not belong here
+ */
+class ExampleHandler
+{
+
+}
+
+/**
+ * @api
+ * @since 100.0.2
+ */
+class ApiHandler
+{
+
+}
+
+/**
+ * @api
+ */
+class AsyncApiHandler
+{
+
+}
+
+/**
+ * @SuppressWarnings(PHPMD.CouplingBetweenObjects)
+ */
+class GroupRepositoryHandler
+{}