#21: WIP add rule for phpdoc

Author: roettigl

Magento2/Sniffs/Commenting/PHPDocFormattingSniff.php

@@ -0,0 +1,108 @@
+<?php
+/**
+ * Copyright © Magento. All rights reserved.
+ * See COPYING.txt for license details.
+ */
+
+namespace Magento2\Sniffs\Commenting;
+
+use Magento2\Sniffs\Legacy\MageEntitySniff;
+use PHP_CodeSniffer\Sniffs\Sniff;
+use PHP_CodeSniffer\Files\File;
+use PHP_CodeSniffer\Util\Tokens;
+
+/**
+ * Detects PHPDoc formatting for constants.
+ */
+class PHPDocFormattingSniff implements Sniff
+{
+    /**
+     * @inheritDoc
+     */
+    public function register()
+    {
+        return [T_FUNCTION];
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function process(File $phpcsFile, $stackPtr)
+    {
+        $tokens = $phpcsFile->getTokens();
+
+        $funcParamStart = $tokens[$stackPtr]['parenthesis_opener'];
+        $funcParamCloser = $tokens[$stackPtr]['parenthesis_closer'];
+        $funcBodyStart = $tokens[$stackPtr]['scope_opener'];
+
+        // search for php7 return type declarations like  func() : string {}
+        $funcReturnTypePos = $phpcsFile->findNext([T_STRING], $funcParamCloser, $funcBodyStart);
+        $funcParamType = null;
+        if ($funcReturnTypePos !== false) {
+            $funcReturnType = $tokens[$funcReturnTypePos]['content'];
+        }
+
+        $funcParamTypeList = $this->getFunctionParameterWithType(
+            array_slice(
+                $tokens,
+                $funcParamStart + 1,
+                $funcParamCloser - $funcParamStart
+            )
+        );
+        $paramType = null;
+
+        if (isset($funcReturnType) && count($funcParamTypeList) !== 0) {
+            // function use php7 return type declarations - no check required
+            return;
+        }
+
+        // search for php doc block
+        $find   = Tokens::$methodPrefixes;
+        $find[] = T_WHITESPACE;
+        $commentEnd = $phpcsFile->findPrevious($find, $stackPtr - 1, null, true);
+        $commentStart = false;
+        if($commentEnd !== false)
+        {
+            $commentStart = '';
+        }
+    }
+
+
+    /**
+     * Returns all parameter as list with there php 7 type declarations like
+     * func(string $arg1, int $arg2)
+     *
+     * @param array $tokens
+     * @return array
+     */
+    private function getFunctionParameterWithType(array $tokens)
+    {
+        $paramType = null;
+        $functionParameterList = [];
+
+        foreach ($tokens as $token) {
+            $type = $token['code'];
+            $content = $token['content'];
+
+            if ($type === T_COMMA) {
+                $paramType = null;
+                continue;
+            }
+
+            if ($type === T_STRING) {
+                $paramType = $content;
+                continue;
+            }
+
+            if ($type === T_VARIABLE && $paramType !== null) {
+                $functionParameterList[] =
+                    [
+                        'content' => $content,
+                        'type' => $paramType
+                    ];
+            }
+        }
+
+        return $functionParameterList;
+    }
+}

Magento2/Tests/Commenting/PHPDocFormattingUnitTest.1.inc

@@ -0,0 +1,40 @@
+<?php
+
+class EverythingIsGoodHere
+{
+    /**
+     * @param string $arg1
+     * @param bool $arg2
+     */
+    private function missingArgumentTypeSoParamsNeedToBeAdded($arg1, $arg2): bool
+    {
+    }
+
+    /**
+     * @return bool
+     */
+    private function presentArgumentTypeSoAnnotationNotNeededButMissingReturnType(string $arg1, bool $arg2)
+    {
+    }
+
+    private function presentArgumentAndReturnTypes(string $arg1, bool $arg2): bool
+    {
+    }
+
+    /**
+     * @throws Exception
+     */
+    private function throwsAnException(): void
+    {
+        throw new \Exception();
+    }
+
+    /**
+     * We have an additional wonderful message here.
+     *
+     * @return void
+     */
+    private function presentGoodDescription(string $arg1, bool $arg2)
+    {
+    }
+}

Magento2/Tests/Commenting/PHPDocFormattingUnitTest.2.inc

@@ -0,0 +1,81 @@
+<?php
+
+class EverythingIsBadHere
+{
+    /**
+     * @param bool $arg2
+     * @param string $arg1
+     */
+    private function wrongParamOrder($arg1, $arg2): bool
+    {
+
+    }
+
+    /**
+     * @param bool $arg2
+     */
+    private function missingParamAnnotation($arg1, $arg2): bool
+    {
+
+    }
+
+    private function missingArgumentAnnotations($arg1, $arg2): bool
+    {
+
+    }
+
+    /**
+     * @param string $arg1
+     * @param bool $arg2
+     * @param bool $arg2
+     */
+    private function paramDuplication($arg1, $arg2): bool
+    {
+
+    }
+
+    /**
+     * @inheritdoc
+     */
+    private function inheritDocShouldNotBeUsed(string $arg1, bool $arg2)
+    {
+
+    }
+
+    /**
+     * @param $arg1
+     * @param $arg2
+     */
+    private function missingParamType($arg1, $arg2): bool
+    {
+
+    }
+
+    /**
+     * Useless description
+     */
+    private function uselessDescription(string $arg1, bool $arg2): bool
+    {
+
+    }
+
+    /**
+     *
+     */
+    private function dockBlockIsEmpty(string $arg1, bool $arg2): bool
+    {
+
+    }
+
+    /**
+     *
+     *
+     * @param string $arg1
+     * @param bool $arg2
+     *
+     */
+    private function redundantLines($arg1, $arg2): bool
+    {
+
+    }
+}

Magento2/Tests/Commenting/PHPDocFormattingUnitTest.php

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