Implement rule from magento#105

Author: udovicic

Magento2/Sniffs/Commenting/ClassAndInterfacePHPDocFormattingSniff.php

@@ -0,0 +1,66 @@
+<?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 extends ConstantsPHPDocFormattingSniff implements Sniff
+{
+    /**
+     * @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->providesMeaning($namePtr, $commentStartPtr, $tokens) !== true) {
+            $phpcsFile->addWarning(
+                'If exists, description should add additional information beyond what the type name already supplies.',
+                $stackPtr,
+                'InvalidDescription'
+            );
+        }
+
+    }
+}

Magento2/Sniffs/Commenting/ConstantsPHPDocFormattingSniff.php

@@ -45,14 +45,34 @@ 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;
         }
 
+        if ($this->providesMeaning($constNamePtr, $commentStartPtr, $tokens) !== true) {
+            $phpcsFile->addWarning(
+                'Constants must have short description if they add information beyond what the constant name supplies.',
+                $stackPtr,
+                'MissingConstantPHPDoc'
+            );
+        }
+    }
+
+    /**
+     * 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
+     */
+    protected function providesMeaning($namePtr, $commentStartPtr, $tokens)
+    {
         $commentCloserPtr = $tokens[$commentStartPtr]['comment_closer'];
+        $name = strtolower(str_replace([' ', '"', '_'], '', $tokens[$namePtr]['content']));
+
         for ($i = $commentStartPtr; $i <= $commentCloserPtr; $i++) {
             $token = $tokens[$i];
 
@@ -61,26 +81,27 @@ public function process(File $phpcsFile, $stackPtr)
                 continue;
             }
 
-            // Comment is the same as constant name
-            $docComment = trim(strtolower($token['content']), ',.');
-            if ($docComment === $constName) {
+            // Wrong kind of string
+            if ($tokens[$i - 2]['code'] === T_DOC_COMMENT_TAG) {
+                continue;
+            }
+
+            // Comment is the same as the origin name
+            $docComment = str_replace(['_', ' ', '.', ','], '', strtolower($token['content']));
+            if ($docComment === $name) {
                 continue;
             }
 
-            // Comment is exactly the same as constant name
-            $docComment = str_replace(' ', '_', $docComment);
-            if ($docComment === $constName) {
+            // 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;
+            return true;
         }
 
-        $phpcsFile->addWarning(
-            'Constants must have short description if they add information beyond what the constant name supplies.',
-            $stackPtr,
-            'MissingConstantPHPDoc'
-        );
+        return false;
     }
 }

Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.1.inc

@@ -0,0 +1,47 @@
+<?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
+ * @package NotFromArroundHere
+ */
+class GreenHandler
+{
+
+}

Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.2.inc

@@ -0,0 +1,47 @@
+<?php
+
+/**
+ * Handler for PHP errors/warnings/notices that converts them to exceptions.
+ */
+interface ErrorHandler
+{
+
+}
+
+interface NotAnErrorHandler
+{
+
+}
+
+/**
+ * Faulty Handler
+ */
+interface FaultyHandler
+{
+
+}
+
+/**
+ * Interface SomeHandler
+ */
+interface SomeHandler
+{
+
+}
+
+/**
+ * YetAnotherHandler
+ */
+interface YetAnotherHandler
+{
+
+}
+
+/**
+ * GreenHandler
+ * @package NotFromArroundHere
+ */
+interface GreenHandler
+{
+
+}

Magento2/Tests/Commenting/ClassAndInterfacePHPDocFormattingUnitTest.php

@@ -0,0 +1,36 @@
+<?php
+
+/**
+ * Copyright © Magento. All rights reserved.
+ * See COPYING.txt for license details.
+ */
+namespace Magento2\Tests\Commenting;
+
+use PHP_CodeSniffer\Tests\Standards\AbstractSniffUnitTest;
+
+/**
+ * Class ClassAndInterfacePHPDocFormattingUnitTest
+ */
+class ClassAndInterfacePHPDocFormattingUnitTest extends AbstractSniffUnitTest
+{
+    /**
+     * @inheritdoc
+     */
+    public function getErrorList()
+    {
+        return [];
+    }
+
+    /**
+     * @inheritdoc
+     */
+    public function getWarningList($testFile = '')
+    {
+        return [
+            19 => 1,
+            27 => 1,
+            35 => 1,
+            44 => 1
+        ];
+    }
+}

Magento2/ruleset.xml

@@ -496,6 +496,10 @@
     </rule>
 
     <!-- Severity 5 warnings: PHPDoc formatting and commenting issues. -->
+    <rule ref="Magento2.Commenting.ClassAndInterfacePHPDocFormatting">
+        <severity>5</severity>
+        <type>warning</type>
+    </rule>
     <rule ref="Magento2.Commenting.ConstantsPHPDocFormatting">
         <severity>5</severity>
         <type>warning</type>