From 33b34f7491268b1eac86db85de079f94ea8f9afa Mon Sep 17 00:00:00 2001
From: jrfnl <jrfnl@users.noreply.github.com>
Date: Sun, 20 Apr 2025 00:02:21 +0200
Subject: [PATCH 1/2] Squiz/VariableComment: make errorcode for "TagNotAllowed"
 warning modular

As things are, the `VariableComment` sniff only allows `@see` tags and `@var` tags in property docblocks.

This practice feels dated to me, as commonly used tags, such as `@link`, `@deprecated` etc are not allowed.

This commit replaces the generic `TagNotAllowed` error code in the sniff with a more modular `[TagName]TagNotAllowed` error code.

This allows for rulesets to selectively ignore the `TagNotAllowed` error code for specific tags the ruleset maintainer wants to allow for the code base under scan.

Includes tests.
---
 .../Commenting/VariableCommentSniff.php       |  3 ++-
 .../Commenting/VariableCommentUnitTest.inc    | 23 +++++++++++++++++++
 .../VariableCommentUnitTest.inc.fixed         | 23 +++++++++++++++++++
 .../Commenting/VariableCommentUnitTest.php    |  7 +++++-
 4 files changed, 54 insertions(+), 2 deletions(-)

diff --git a/src/Standards/Squiz/Sniffs/Commenting/VariableCommentSniff.php b/src/Standards/Squiz/Sniffs/Commenting/VariableCommentSniff.php
index 569466ba61..2227f66348 100644
--- a/src/Standards/Squiz/Sniffs/Commenting/VariableCommentSniff.php
+++ b/src/Standards/Squiz/Sniffs/Commenting/VariableCommentSniff.php
@@ -111,7 +111,8 @@ public function processMemberVar(File $phpcsFile, $stackPtr)
             } else {
                 $error = '%s tag is not allowed in member variable comment';
                 $data  = [$tokens[$tag]['content']];
-                $phpcsFile->addWarning($error, $tag, 'TagNotAllowed', $data);
+                $code  = ucwords(ltrim($tokens[$tag]['content'], '@')).'TagNotAllowed';
+                $phpcsFile->addWarning($error, $tag, $code, $data);
             }//end if
         }//end foreach
 
diff --git a/src/Standards/Squiz/Tests/Commenting/VariableCommentUnitTest.inc b/src/Standards/Squiz/Tests/Commenting/VariableCommentUnitTest.inc
index 170b84fe69..08b15e2c44 100644
--- a/src/Standards/Squiz/Tests/Commenting/VariableCommentUnitTest.inc
+++ b/src/Standards/Squiz/Tests/Commenting/VariableCommentUnitTest.inc
@@ -476,3 +476,26 @@ class PHP84FinalProperties {
      */
     final int $hasDocblock;
 }
+
+// phpcs:disable Squiz.Commenting.VariableComment.SinceTagNotAllowed
+// phpcs:disable Squiz.Commenting.VariableComment.DeprecatedTagNotAllowed
+class AllowMoreForSelectivelyIgnoringDisallowedTags {
+    /**
+     * @var string
+     *
+     * @since      3.1
+     * @deprecated 10.5
+     */
+    public string $propertyWithExtraTags;
+
+    /**
+     * @var string
+     *
+     * @link       https://example.org/some-link
+     * @api
+     * @param string This tag is not allowed.
+     */
+    public $theAboveExtraTagsAreStillNotAllowed;
+}
+
+// phpcs:enable Squiz.Commenting.VariableComment
diff --git a/src/Standards/Squiz/Tests/Commenting/VariableCommentUnitTest.inc.fixed b/src/Standards/Squiz/Tests/Commenting/VariableCommentUnitTest.inc.fixed
index 0b3c5a4b9e..36fe4688cb 100644
--- a/src/Standards/Squiz/Tests/Commenting/VariableCommentUnitTest.inc.fixed
+++ b/src/Standards/Squiz/Tests/Commenting/VariableCommentUnitTest.inc.fixed
@@ -476,3 +476,26 @@ class PHP84FinalProperties {
      */
     final int $hasDocblock;
 }
+
+// phpcs:disable Squiz.Commenting.VariableComment.SinceTagNotAllowed
+// phpcs:disable Squiz.Commenting.VariableComment.DeprecatedTagNotAllowed
+class AllowMoreForSelectivelyIgnoringDisallowedTags {
+    /**
+     * @var string
+     *
+     * @since      3.1
+     * @deprecated 10.5
+     */
+    public string $propertyWithExtraTags;
+
+    /**
+     * @var string
+     *
+     * @link       https://example.org/some-link
+     * @api
+     * @param string This tag is not allowed.
+     */
+    public $theAboveExtraTagsAreStillNotAllowed;
+}
+
+// phpcs:enable Squiz.Commenting.VariableComment
diff --git a/src/Standards/Squiz/Tests/Commenting/VariableCommentUnitTest.php b/src/Standards/Squiz/Tests/Commenting/VariableCommentUnitTest.php
index 01691216ca..bda0cda65e 100644
--- a/src/Standards/Squiz/Tests/Commenting/VariableCommentUnitTest.php
+++ b/src/Standards/Squiz/Tests/Commenting/VariableCommentUnitTest.php
@@ -81,7 +81,12 @@ public function getErrorList()
      */
     public function getWarningList()
     {
-        return [93 => 1];
+        return [
+            93  => 1,
+            494 => 1,
+            495 => 1,
+            496 => 1,
+        ];
 
     }//end getWarningList()
 

From 20994a2d1e32892a7579a4b70c3045ccc62777b5 Mon Sep 17 00:00:00 2001
From: jrfnl <jrfnl@users.noreply.github.com>
Date: Sun, 20 Apr 2025 00:03:38 +0200
Subject: [PATCH 2/2] CS: allow `@link` and `@deprecated` in property docblocks

... for this codebase.
---
 phpcs.xml.dist | 10 ++++------
 1 file changed, 4 insertions(+), 6 deletions(-)

diff --git a/phpcs.xml.dist b/phpcs.xml.dist
index 237034fa7d..2dd649705b 100644
--- a/phpcs.xml.dist
+++ b/phpcs.xml.dist
@@ -47,7 +47,10 @@
     <rule ref="Squiz.Commenting.PostStatementComment">
         <exclude name="Squiz.Commenting.PostStatementComment.AnnotationFound"/>
     </rule>
-    <rule ref="Squiz.Commenting.VariableComment"/>
+    <rule ref="Squiz.Commenting.VariableComment">
+        <exclude name="Squiz.Commenting.VariableComment.DeprecatedTagNotAllowed"/>
+        <exclude name="Squiz.Commenting.VariableComment.LinkTagNotAllowed"/>
+    </rule>
     <rule ref="Squiz.Formatting.OperatorBracket"/>
     <rule ref="Squiz.Functions.FunctionDeclarationArgumentSpacing"/>
     <rule ref="Squiz.Operators.ComparisonOperatorUsage"/>
@@ -154,9 +157,4 @@
         <exclude-pattern>src/Standards/Generic/Sniffs/Commenting/TodoSniff\.php</exclude-pattern>
         <exclude-pattern>src/Standards/Generic/Tests/Commenting/TodoUnitTest\.php</exclude-pattern>
     </rule>
-
-    <!-- @see https://github.com/PHPCSStandards/PHP_CodeSniffer/pull/122#discussion_r1414167897 -->
-    <rule ref="Squiz.Commenting.VariableComment">
-        <exclude-pattern>src/Util/Tokens\.php</exclude-pattern>
-    </rule>
 </ruleset>