From 2cb805a36d64a57316d32d493a27f75962fb1fdf Mon Sep 17 00:00:00 2001
From: Stjepan Udovicic <stjepan.udovicic@inchoo.net>
Date: Sun, 23 Jun 2019 17:36:51 +0200
Subject: [PATCH 1/2] Implement rule from #107

---
 .../ConstantsPHPDocFormattingSniff.php        | 86 +++++++++++++++++++
 .../ConstantsPHPDocFormattingUnitTest.1.inc   | 18 ++++
 .../ConstantsPHPDocFormattingUnitTest.2.inc   | 21 +++++
 .../ConstantsPHPDocFormattingUnitTest.php     | 39 +++++++++
 Magento2/ruleset.xml                          |  4 +
 5 files changed, 168 insertions(+)
 create mode 100644 Magento2/Sniffs/Commenting/ConstantsPHPDocFormattingSniff.php
 create mode 100644 Magento2/Tests/Commenting/ConstantsPHPDocFormattingUnitTest.1.inc
 create mode 100644 Magento2/Tests/Commenting/ConstantsPHPDocFormattingUnitTest.2.inc
 create mode 100644 Magento2/Tests/Commenting/ConstantsPHPDocFormattingUnitTest.php

diff --git a/Magento2/Sniffs/Commenting/ConstantsPHPDocFormattingSniff.php b/Magento2/Sniffs/Commenting/ConstantsPHPDocFormattingSniff.php
new file mode 100644
index 00000000..303ca25e
--- /dev/null
+++ b/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'
+        );
+    }
+}
diff --git a/Magento2/Tests/Commenting/ConstantsPHPDocFormattingUnitTest.1.inc b/Magento2/Tests/Commenting/ConstantsPHPDocFormattingUnitTest.1.inc
new file mode 100644
index 00000000..e3d2000a
--- /dev/null
+++ b/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;
+}
diff --git a/Magento2/Tests/Commenting/ConstantsPHPDocFormattingUnitTest.2.inc b/Magento2/Tests/Commenting/ConstantsPHPDocFormattingUnitTest.2.inc
new file mode 100644
index 00000000..c4189ff1
--- /dev/null
+++ b/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;
+}
diff --git a/Magento2/Tests/Commenting/ConstantsPHPDocFormattingUnitTest.php b/Magento2/Tests/Commenting/ConstantsPHPDocFormattingUnitTest.php
new file mode 100644
index 00000000..b3042b18
--- /dev/null
+++ b/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
+        ];
+    }
+}
diff --git a/Magento2/ruleset.xml b/Magento2/ruleset.xml
index 95e91e69..4e54433d 100644
--- a/Magento2/ruleset.xml
+++ b/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>

From 3fe6883f4a131edd6b9cf052fcd327654fe1c613 Mon Sep 17 00:00:00 2001
From: Lena Orobei <oorobei@magento.com>
Date: Wed, 17 Jul 2019 13:37:04 -0500
Subject: [PATCH 2/2] magento/magento-coding-standard#107: [New Rule] Implement
 sniff for constants PHPDoc formatting - added strict comparison - changed
 sequence in the ruleset.xml

---
 .../Sniffs/Commenting/ConstantsPHPDocFormattingSniff.php  | 4 ++--
 Magento2/ruleset.xml                                      | 8 ++++----
 2 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/Magento2/Sniffs/Commenting/ConstantsPHPDocFormattingSniff.php b/Magento2/Sniffs/Commenting/ConstantsPHPDocFormattingSniff.php
index 303ca25e..df59c9ac 100644
--- a/Magento2/Sniffs/Commenting/ConstantsPHPDocFormattingSniff.php
+++ b/Magento2/Sniffs/Commenting/ConstantsPHPDocFormattingSniff.php
@@ -31,8 +31,8 @@ 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)
+        if ($tokens[$stackPtr]['code'] !== T_CONST
+            && !($tokens[$stackPtr]['content'] === 'define' && $tokens[$stackPtr + 1]['code'] === T_OPEN_PARENTHESIS)
         ) {
             return;
         }
diff --git a/Magento2/ruleset.xml b/Magento2/ruleset.xml
index 4e54433d..98100eae 100644
--- a/Magento2/ruleset.xml
+++ b/Magento2/ruleset.xml
@@ -44,10 +44,6 @@
         <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>
@@ -500,6 +496,10 @@
     </rule>
 
     <!-- Severity 5 warnings: PHPDoc formatting and commenting issues. -->
+    <rule ref="Magento2.Commenting.ConstantsPHPDocFormatting">
+        <severity>5</severity>
+        <type>warning</type>
+    </rule>
     <rule ref="Squiz.Commenting.DocCommentAlignment">
         <severity>5</severity>
         <type>warning</type>