#58 : Implement sniff for class properties PHPDoc formatting

Magento2/Sniffs/Commenting/ClassPropertyPHPDocFormattingSniff.php

@@ -0,0 +1,90 @@
+<?php
+namespace Magento2\Sniffs\Commenting;
+
+use PHP_CodeSniffer\Files\File;
+use PHP_CodeSniffer\Sniffs\AbstractVariableSniff;
+
+/**
+ * Class ClassPropertyPHPDocFormattingSniff
+ */
+class ClassPropertyPHPDocFormattingSniff extends AbstractVariableSniff
+{
+
+    /**
+     * @var array
+     */
+    private $ignoreTokens = [
+        T_PUBLIC,
+        T_PRIVATE,
+        T_PROTECTED,
+        T_VAR,
+        T_STATIC,
+        T_WHITESPACE,
+    ];
+
+    /**
+     * @param File $phpcsFile
+     * @param int $stackPtr
+     * @return int|void
+     */
+    public function processMemberVar(File $phpcsFile, $stackPtr)
+    {
+        $tokens = $phpcsFile->getTokens();
+
+        $commentEnd = $phpcsFile->findPrevious($this->ignoreTokens, ($stackPtr - 1), null, true);
+        if ($commentEnd === false
+            || ($tokens[$commentEnd]['code'] !== T_DOC_COMMENT_CLOSE_TAG
+                && $tokens[$commentEnd]['code'] !== T_COMMENT)
+        ) {
+            $phpcsFile->addWarning('Missing class property doc comment', $stackPtr, 'Missing');
+            return;
+        }
+
+        $commentStart = $tokens[$commentEnd]['comment_opener'];
+
+        $foundVar = null;
+        foreach ($tokens[$commentStart]['comment_tags'] as $tag) {
+            if ($tokens[$tag]['content'] === '@var') {
+                if ($foundVar !== null) {
+                    $error = 'Only one @var tag is allowed in a class property comment';
+                    $phpcsFile->addWarning($error, $tag, 'DuplicateVar');
+                } else {
+                    $foundVar = $tag;
+                }
+            }
+        }
+
+        if ($foundVar === null) {
+            $error = 'Missing @var tag in class property comment';
+            $phpcsFile->addWarning($error, $commentEnd, 'MissingVar');
+            return;
+        }
+
+        $string = $phpcsFile->findNext(T_DOC_COMMENT_STRING, $foundVar, $commentEnd);
+        if ($string === false || $tokens[$string]['line'] !== $tokens[$foundVar]['line']) {
+            $error = 'Content missing for @var tag in class property comment';
+            $phpcsFile->addWarning($error, $foundVar, 'EmptyVar');
+            return;
+        }
+    }
+
+    /**
+     * @param File $phpcsFile
+     * @param int $stackPtr
+     * @return int|void
+     * phpcs:disable Magento2.CodeAnalysis.EmptyBlock
+     */
+    protected function processVariable(File $phpcsFile, $stackPtr)
+    {
+    }
+
+    /**
+     * @param File $phpcsFile
+     * @param int $stackPtr
+     * @return int|void
+     * phpcs:disable Magento2.CodeAnalysis.EmptyBlock
+     */
+    protected function processVariableInString(File $phpcsFile, $stackPtr)
+    {
+    }
+}

Magento2/Sniffs/Exceptions/DirectThrowSniff.php

@@ -16,6 +16,7 @@ class DirectThrowSniff implements Sniff
     /**
      * String representation of warning.
      * phpcs:disable Generic.Files.LineLength.TooLong
+     * @var string
      */
     protected $warningMessage = 'Direct throw of generic Exception is discouraged. Use context specific instead.';
     //phpcs:enable

Magento2/Sniffs/Security/SuperglobalSniff.php

@@ -42,7 +42,7 @@ class SuperglobalSniff implements Sniff
     protected $errorCode = 'SuperglobalUsageError';
 
     /**
-     * @inheritdoc
+     * @var array
      */
     protected $superGlobalErrors = [
         '$GLOBALS',
@@ -55,7 +55,7 @@ class SuperglobalSniff implements Sniff
     ];
 
     /**
-     * @inheritdoc
+     * @var array
      */
     protected $superGlobalWarning = [
         '$_COOKIE', //sometimes need to get list of all cookies array and there are no methods to do that in M2

Magento2/Tests/Commenting/ClassPropertyPHPDocFormattingUnitTest.inc

@@ -0,0 +1,35 @@
+<?php
+
+class Foo
+{
+    /**
+     * @var Foo
+     */
+    private $_classAttribute = '';
+
+    /**
+     * Foo
+     */
+    private $_withoutClassAttribute = '';
+
+    /**
+     * @var Test
+     *
+     * Short Description
+     */
+    private $_classAttributeWithShortDescription = '';
+
+    /**
+     * @var
+     */
+    private $_emptyClassAttributeContent = '';
+
+
+    /**
+     * @var Foo
+     * @var Bar
+     */
+    private $_multipleClassAttribute = '';
+
+    private $_missingDocBlockClassAttribute = '';
+}

Magento2/Tests/Commenting/ClassPropertyPHPDocFormattingUnitTest.php

@@ -0,0 +1,32 @@
+<?php
+/**
+ * Copyright © Magento. All rights reserved.
+ * See COPYING.txt for license details.
+ */
+namespace Magento2\Tests\Commenting;
+
+use PHP_CodeSniffer\Tests\Standards\AbstractSniffUnitTest;
+
+class ClassPropertyPHPDocFormattingUnitTest extends AbstractSniffUnitTest
+{
+    /**
+     * @inheritdoc
+     */
+    public function getErrorList()
+    {
+        return [];
+    }
+
+    /**
+     * @inheritdoc
+     */
+    public function getWarningList()
+    {
+        return [
+            12 => 1,
+            23 => 1,
+            30 => 1,
+            34 => 1
+        ];
+    }
+}

Magento2/ruleset.xml

@@ -528,6 +528,10 @@
         <severity>5</severity>
         <type>warning</type>
     </rule>
+    <rule ref="Magento2.Commenting.ClassPropertyPHPDocFormatting">
+        <severity>5</severity>
+        <type>warning</type>
+    </rule>
     <rule ref="Magento2.Commenting.ConstantsPHPDocFormatting">
         <severity>5</severity>
         <type>warning</type>