From 308391d6c711be54434289b0762b0b7afc8dbba9 Mon Sep 17 00:00:00 2001
From: Ferdinand Kuhl <f.kuhl@digital-competence.de>
Date: Sat, 30 Apr 2022 21:27:42 +0200
Subject: [PATCH] Allow @inheritdoc instead of @var on property

---
 .../Commenting/VariableCommentSniff.php       | 48 +++++++++++++++++++
 src/DigiComp/ruleset.xml                      | 13 ++---
 src/Inwebs/ruleset.xml                        |  6 ++-
 .../Commenting/VariableCommentSniffTest.php   | 14 ++++++
 .../Sniffs/Commenting/data/comments.php       | 22 +++++++++
 5 files changed, 96 insertions(+), 7 deletions(-)
 create mode 100644 src/DigiComp/Sniffs/Commenting/VariableCommentSniff.php
 create mode 100644 tests/DigiComp/Sniffs/Commenting/VariableCommentSniffTest.php
 create mode 100644 tests/DigiComp/Sniffs/Commenting/data/comments.php

diff --git a/src/DigiComp/Sniffs/Commenting/VariableCommentSniff.php b/src/DigiComp/Sniffs/Commenting/VariableCommentSniff.php
new file mode 100644
index 0000000..d181735
--- /dev/null
+++ b/src/DigiComp/Sniffs/Commenting/VariableCommentSniff.php
@@ -0,0 +1,48 @@
+<?php
+
+namespace DigiComp\PhpCodesniffer\DigiComp\Sniffs\Commenting;
+
+use PHP_CodeSniffer\Files\File;
+
+class VariableCommentSniff extends \PHP_CodeSniffer\Standards\Squiz\Sniffs\Commenting\VariableCommentSniff
+{
+    public function processMemberVar(File $phpcsFile, $stackPtr)
+    {
+        $tokens = $phpcsFile->getTokens();
+        $ignore = [
+            \T_PUBLIC,
+            \T_PRIVATE,
+            \T_PROTECTED,
+            \T_VAR,
+            \T_STATIC,
+            \T_WHITESPACE,
+            \T_STRING,
+            \T_NS_SEPARATOR,
+            \T_NULLABLE,
+        ];
+
+        $commentEnd = $phpcsFile->findPrevious($ignore, ($stackPtr - 1), null, true);
+
+
+        $commentStart = $tokens[$commentEnd]['comment_opener'];
+
+        $foundVar = null;
+        foreach ($tokens[$commentStart]['comment_tags'] as $tag) {
+            if (
+                $tokens[$tag]['content'] === '@var'
+                || $tokens[$tag]['content'] === '@inheritDoc'
+            ) {
+                $foundVar = $tag;
+            }
+        }
+
+        // The @var tag is the only one we require.
+        if ($foundVar === null) {
+            $error = 'Missing @var or @inheritDoc tag in member variable comment';
+            $phpcsFile->addWarning($error, $commentEnd, 'MissingVarOrInheritDoc');
+            return;
+        }
+
+        parent::processMemberVar($phpcsFile, $stackPtr);
+    }
+}
diff --git a/src/DigiComp/ruleset.xml b/src/DigiComp/ruleset.xml
index fa0b776..398e8ae 100644
--- a/src/DigiComp/ruleset.xml
+++ b/src/DigiComp/ruleset.xml
@@ -9,13 +9,14 @@
     <rule ref="PSR12"/>
 
     <rule ref="Generic.Arrays.DisallowLongArraySyntax"/>
-    <rule ref="Squiz.Commenting.VariableComment">
-        <exclude name="Squiz.Commenting.VariableComment.VarOrder" />
-        <exclude name="Squiz.Commenting.VariableComment.TagNotAllowed" />
-        <exclude name="Squiz.Commenting.VariableComment.IncorrectVarType" />
+    <rule ref="DigiComp.Commenting.VariableComment">
+        <exclude name="DigiComp.Commenting.VariableComment.VarOrder" />
+        <exclude name="DigiComp.Commenting.VariableComment.TagNotAllowed" />
+        <exclude name="DigiComp.Commenting.VariableComment.IncorrectVarType" />
+        <exclude name="DigiComp.Commenting.VariableComment.MissingVar" />
     </rule>
-    <!-- TODO: what about new PHP 7.4 code base, where property annotations may get useles -->
-    <rule ref="Squiz.Commenting.VariableComment.Missing">
+    <!-- TODO: what about new PHP 7.4 code base, where property annotations may get useless? -->
+    <rule ref="DigiComp.Commenting.VariableComment.Missing">
         <type>warning</type>
         <severity>4</severity>
     </rule>
diff --git a/src/Inwebs/ruleset.xml b/src/Inwebs/ruleset.xml
index d02d568..f18982a 100644
--- a/src/Inwebs/ruleset.xml
+++ b/src/Inwebs/ruleset.xml
@@ -13,7 +13,11 @@
             <property name="spacing" value="0"/>
         </properties>
     </rule>
-    <rule ref="Squiz.Commenting.VariableComment.Missing">
+    <rule ref="DigiComp.Commenting.VariableComment.Missing">
+        <type>error</type>
+        <severity>6</severity>
+    </rule>
+    <rule ref="DigiComp.Commenting.VariableComment.MissingVarOrInheritDoc">
         <type>error</type>
         <severity>6</severity>
     </rule>
diff --git a/tests/DigiComp/Sniffs/Commenting/VariableCommentSniffTest.php b/tests/DigiComp/Sniffs/Commenting/VariableCommentSniffTest.php
new file mode 100644
index 0000000..b153d4c
--- /dev/null
+++ b/tests/DigiComp/Sniffs/Commenting/VariableCommentSniffTest.php
@@ -0,0 +1,14 @@
+<?php
+
+namespace DigiComp\PhpCodesniffer\DigiComp\Sniffs\Commenting;
+
+use SlevomatCodingStandard\Sniffs\TestCase;
+
+class VariableCommentSniffTest extends TestCase
+{
+    public function testErrors(): void
+    {
+        $report = self::checkFile(__DIR__ . '/data/comments.php');
+        self::assertCount(1, $report->getWarnings()[20][6]);
+    }
+}
diff --git a/tests/DigiComp/Sniffs/Commenting/data/comments.php b/tests/DigiComp/Sniffs/Commenting/data/comments.php
new file mode 100644
index 0000000..4452582
--- /dev/null
+++ b/tests/DigiComp/Sniffs/Commenting/data/comments.php
@@ -0,0 +1,22 @@
+<?php
+
+class A {
+    /**
+     * @var string
+     */
+    protected $var;
+}
+
+class B extends A {
+    /**
+     * @inheritDoc
+     */
+    protected $var;
+}
+
+class C extends A {
+    /**
+     * No inherit
+     */
+    protected $var;
+}