Implement rule from #107

Author: udovicic

Magento2/Sniffs/Commenting/ConstantsPHPDocFormattingSniff.php

@@ -0,0 +1,86 @@
+<?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 constants.
+ */
+class ConstantsPHPDocFormattingSniff implements Sniff
+{
+    /**
+     * @inheritDoc
+     */
+    public function register()
+    {
+        return [
+            T_CONST,
+            T_STRING
+        ];
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function process(File $phpcsFile, $stackPtr)
+    {
+        $tokens = $phpcsFile->getTokens();
+
+        if ($tokens[$stackPtr]['code'] != T_CONST
+            && !($tokens[$stackPtr]['content'] == 'define' && $tokens[$stackPtr+1]['code'] == T_OPEN_PARENTHESIS)
+        ) {
+            return;
+        }
+
+        $constNamePtr = $phpcsFile->findNext(
+            ($tokens[$stackPtr]['code'] === T_CONST) ? T_STRING : T_CONSTANT_ENCAPSED_STRING,
+            $stackPtr + 1,
+            null,
+            false,
+            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;
+        }
+
+        $phpcsFile->addWarning(
+            'Constants must have short description if they add information beyond what the constant name supplies.',
+            $stackPtr,
+            'MissingConstantPHPDoc'
+        );
+    }
+}

Magento2/Tests/Commenting/ConstantsPHPDocFormattingUnitTest.1.inc

@@ -0,0 +1,18 @@
+<?php
+
+/**
+ * Directory separator shorthand, intended to make code more readable.
+ */
+define('DS', DIRECTORY_SEPARATOR);
+
+define('BP', dirname(__FILE__));
+
+class Profiler
+{
+    const NESTING_SEPARATOR = '->';
+
+    /**
+     * Unlike first const, this one is not self explanatory.
+     */
+    const NUMBER_TWO = 2;
+}

Magento2/Tests/Commenting/ConstantsPHPDocFormattingUnitTest.2.inc

@@ -0,0 +1,21 @@
+<?php
+/**
+ * Nesting separator.
+ */
+define("NESTING_SEPARATOR", '->0');
+
+/**  */
+define('NUMBER_ONE', 1);
+
+class Profiler
+{
+    /**
+     * Nesting separator.
+     */
+    const NESTING_SEPARATOR = '->';
+
+    /**
+     *
+     */
+    const NUMBER_TWO = 2;
+}

Magento2/Tests/Commenting/ConstantsPHPDocFormattingUnitTest.php

@@ -0,0 +1,39 @@
+<?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 ConstantsPHPDocFormattingUnitTest extends AbstractSniffUnitTest
+{
+    /**
+     * @inheritdoc
+     */
+    public function getErrorList()
+    {
+        return [];
+    }
+
+    /**
+     * @inheritdoc
+     */
+    public function getWarningList($testFile = '')
+    {
+        if ($testFile === 'ConstantsPHPDocFormattingUnitTest.1.inc') {
+            return [];
+        }
+
+        return [
+            5 => 1,
+            8 => 1,
+            15 => 1,
+            20 => 1
+        ];
+    }
+}

Magento2/ruleset.xml

@@ -44,6 +44,10 @@
         <severity>10</severity>
         <type>error</type>
     </rule>
+    <rule ref="Magento2.Commenting.ConstantsPHPDocFormatting">
+        <severity>5</severity>
+        <type>warning</type>
+    </rule>
     <rule ref="Magento2.PHP.FinalImplementation">
         <severity>10</severity>
         <type>error</type>