From 629e9b6ba0f291fcaa43c669fcfe865edc87fb22 Mon Sep 17 00:00:00 2001
From: Jay McPartland <jay@bigbite.net>
Date: Fri, 7 Mar 2025 13:34:12 +0000
Subject: [PATCH 1/3] Reimplement documentation sniffs

The WordPress-Docs ruleset that we were using
excludes several sniff codes that are useful
to us. So, this change removes that ruleset
and adds back many of the sniffs it includes,
but with adjustments that better suit the
needs of Big Bite.
---
 BigBite/ruleset.xml   | 60 +++++++++++++++++++++++++++++++++++--------
 phpcs.xml.dist.sample |  2 +-
 2 files changed, 51 insertions(+), 11 deletions(-)

diff --git a/BigBite/ruleset.xml b/BigBite/ruleset.xml
index 7059ccb..83b8e26 100644
--- a/BigBite/ruleset.xml
+++ b/BigBite/ruleset.xml
@@ -49,17 +49,10 @@
   <!-- Built asset files from Build Tools. -->
   <exclude-pattern>*/dist/*.asset.php</exclude-pattern>
 
-  <rule ref="WordPress">
-    <!-- Don't enforce long-form array syntax. -->
+  <!-- Use all of WP's ruleset, barring docs, and other rules that don't make sense for us. -->
+  <rule ref="WordPress-Extra">
+    <!-- Don't enforce long-form array syntax; we use short arrays exclusively. -->
     <exclude name="Universal.Arrays.DisallowShortArraySyntax.Found" />
-    <!-- Don't enforce a file comment, since we enforce class, method, and function comments. -->
-    <exclude name="Squiz.Commenting.FileComment" />
-    <!-- Be slightly less aggressive about DocBlock formatting. -->
-    <exclude name="Squiz.Commenting.FunctionComment.ParamCommentFullStop" />
-    <exclude name="Squiz.Commenting.FunctionComment.ThrowsNoFullStop" />
-    <exclude name="Squiz.Commenting.FunctionComment.ThrowsNotCapital" />
-    <!-- Don't enforce a period at the end of comments. -->
-    <exclude name="Squiz.Commenting.InlineComment.InvalidEndChar" />
     <!-- For consistency, allow a blank line before the class closing brace -->
     <exclude name="PSR2.Classes.ClassDeclaration.CloseBraceAfterBody" />
     <!-- We have our own file name sniff - WP doesn't account for abstract classes -->
@@ -70,8 +63,13 @@
     <exclude name="WordPress.WP.CapitalPDangit.Misspelled" />
   </rule>
 
+  <!-- Use all of WP VIP's ruleset. -->
   <rule ref="WordPress-VIP-Go" />
 
+  <!-- ################ -->
+  <!-- Additional rules -->
+  <!-- ################ -->
+
   <!-- Disallow closures longer than 5 (warn) or 8 (error) lines long -->
   <rule ref="Universal.FunctionDeclarations.NoLongClosures" />
   <!-- Enforce non-private, non-abstract methods in traits to be declared as final -->
@@ -87,6 +85,11 @@
     <exclude name="Generic.CodeAnalysis.UnusedFunctionParameter.FoundInImplementedInterfaceAfterLastUsed" />
     <exclude name="Generic.CodeAnalysis.UnusedFunctionParameter.FoundInImplementedInterfaceBeforeLastUsed" />
   </rule>
+  <!-- Include documentation sniff from WordPress-Docs -->
+  <rule ref="Generic.Commenting.DocComment">
+    <!-- Allow other tags to come before @param comments - @see, @link, etc. -->
+    <exclude name="Generic.Commenting.DocComment.ParamNotFirst" />
+  </rule>
   <!-- Warn when there's todo/fixme notations -->
   <rule ref="Generic.Commenting.Todo" />
   <rule ref="Generic.Commenting.Fixme" />
@@ -109,6 +112,43 @@
   <!-- Check that the closing braces of scopes are aligned correctly. -->
   <rule ref="PEAR.WhiteSpace.ScopeClosingBrace" />
 
+  <!-- Include documentation sniffs from WordPress-Docs. -->
+  <rule ref="Squiz.Commenting.BlockComment">
+    <!-- We do not like empty lines after block comments. -->
+    <exclude name="Squiz.Commenting.BlockComment.NoEmptyLineAfter" />
+    <!-- Allow for /* translators: ... */ comments. -->
+    <exclude name="Squiz.Commenting.BlockComment.SingleLine" />
+    <!-- Uses spaces for indentation. -->
+    <exclude name="Squiz.Commenting.BlockComment.FirstLineIndent" />
+    <exclude name="Squiz.Commenting.BlockComment.LineIndent" />
+    <exclude name="Squiz.Commenting.BlockComment.LastLineIndent" />
+  </rule>
+  <rule ref="Squiz.Commenting.ClassComment" />
+  <rule ref="Squiz.Commenting.DocCommentAlignment" />
+  <rule ref="Squiz.Commenting.EmptyCatchComment" />
+  <rule ref="Squiz.Commenting.FunctionComment">
+    <!-- We prefer shorthand int/bool over integer/boolean. -->
+    <exclude name="Squiz.Commenting.FunctionComment.IncorrectParamVarName" />
+    <exclude name="Squiz.Commenting.FunctionComment.InvalidReturn" />
+    <!-- Be slightly less aggressive about DocBlock formatting. -->
+    <exclude name="Squiz.Commenting.FunctionComment.ParamCommentFullStop" />
+    <exclude name="Squiz.Commenting.FunctionComment.ThrowsNoFullStop" />
+    <exclude name="Squiz.Commenting.FunctionComment.ThrowsNotCapital" />
+  </rule>
+  <rule ref="Squiz.Commenting.FunctionCommentThrowTag" />
+  <rule ref="Squiz.Commenting.InlineComment">
+    <!-- Allow inline docblocks. -->
+    <exclude name="Squiz.Commenting.InlineComment.DocBlock" />
+    <!-- Don't enforce a period at the end of comments. -->
+    <exclude name="Squiz.Commenting.InlineComment.InvalidEndChar" />
+    <!-- Allow "translators:" comments. -->
+    <exclude name="Squiz.Commenting.InlineComment.NotCapital" />
+  </rule>
+  <rule ref="Squiz.Commenting.PostStatementComment" />
+  <rule ref="Squiz.Commenting.VariableComment">
+    <!-- We prefer shorthand int/bool over integer/boolean. -->
+    <exclude name="Squiz.Commenting.VariableComment.IncorrectVarType" />
+  </rule>
   <!-- Force debug output function calls to error. -->
   <rule ref="Squiz.PHP.DiscouragedFunctions">
     <properties>
diff --git a/phpcs.xml.dist.sample b/phpcs.xml.dist.sample
index 3d0337b..1e29836 100644
--- a/phpcs.xml.dist.sample
+++ b/phpcs.xml.dist.sample
@@ -1,5 +1,5 @@
 <?xml version="1.0"?>
-<ruleset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="Example Project" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/squizlabs/PHP_CodeSniffer/master/phpcs.xsd">
+<ruleset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="Example Project" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/PHPCSStandards/PHP_CodeSniffer/master/phpcs.xsd">
   <description>This is an example project</description>
 
   <exclude-pattern>/root/path/to/file.php</exclude-pattern>

From bc25879f258ed02058bf9f8c921562a0a6f86770 Mon Sep 17 00:00:00 2001
From: Jay McPartland <jay@bigbite.net>
Date: Fri, 7 Mar 2025 13:40:00 +0000
Subject: [PATCH 2/3] Improve ruleset comments

---
 BigBite/ruleset.xml | 30 +++++++++++++++++++-----------
 1 file changed, 19 insertions(+), 11 deletions(-)

diff --git a/BigBite/ruleset.xml b/BigBite/ruleset.xml
index 83b8e26..017769f 100644
--- a/BigBite/ruleset.xml
+++ b/BigBite/ruleset.xml
@@ -53,13 +53,13 @@
   <rule ref="WordPress-Extra">
     <!-- Don't enforce long-form array syntax; we use short arrays exclusively. -->
     <exclude name="Universal.Arrays.DisallowShortArraySyntax.Found" />
-    <!-- For consistency, allow a blank line before the class closing brace -->
+    <!-- For consistency, allow a blank line before the class closing brace. -->
     <exclude name="PSR2.Classes.ClassDeclaration.CloseBraceAfterBody" />
-    <!-- We have our own file name sniff - WP doesn't account for abstract classes -->
+    <!-- We have our own file name sniff - WP doesn't account for abstract classes. -->
     <exclude name="WordPress.Files.FileName" />
-    <!-- Shorthand ternaries can be okay - should be checked at PR review time -->
+    <!-- Shorthand ternaries can be okay - should be checked at PR review time. -->
     <exclude name="Universal.Operators.DisallowShortTernary.Found" />
-    <!-- Don't cause build failures out of spite -->
+    <!-- There are scenarios where this would cause issues. -->
     <exclude name="WordPress.WP.CapitalPDangit.Misspelled" />
   </rule>
 
@@ -70,14 +70,14 @@
   <!-- Additional rules -->
   <!-- ################ -->
 
-  <!-- Disallow closures longer than 5 (warn) or 8 (error) lines long -->
+  <!-- Disallow closures longer than 5 (warn) or 8 (error) lines long. -->
   <rule ref="Universal.FunctionDeclarations.NoLongClosures" />
-  <!-- Enforce non-private, non-abstract methods in traits to be declared as final -->
+  <!-- Enforce non-private, non-abstract methods in traits to be declared as final. -->
   <rule ref="Universal.FunctionDeclarations.RequireFinalMethodsInTraits" />
-  <!-- Enforce the use of the boolean && and || operators instead of the logical and/or operators -->
+  <!-- Enforce the use of the boolean && and || operators instead of the logical and/or operators. -->
   <rule ref="Universal.Operators.DisallowLogicalAndOr" />
 
-  <!-- Warn about unused function parameters -->
+  <!-- Warn about unused function parameters. -->
   <rule ref="Generic.CodeAnalysis.UnusedFunctionParameter">
     <!-- Except under circumstances in which they make sense. -->
     <exclude name="Generic.CodeAnalysis.UnusedFunctionParameter.FoundBeforeLastUsed" />
@@ -85,7 +85,7 @@
     <exclude name="Generic.CodeAnalysis.UnusedFunctionParameter.FoundInImplementedInterfaceAfterLastUsed" />
     <exclude name="Generic.CodeAnalysis.UnusedFunctionParameter.FoundInImplementedInterfaceBeforeLastUsed" />
   </rule>
-  <!-- Include documentation sniff from WordPress-Docs -->
+  <!-- Check block comments for conformity.. -->
   <rule ref="Generic.Commenting.DocComment">
     <!-- Allow other tags to come before @param comments - @see, @link, etc. -->
     <exclude name="Generic.Commenting.DocComment.ParamNotFirst" />
@@ -112,20 +112,24 @@
   <!-- Check that the closing braces of scopes are aligned correctly. -->
   <rule ref="PEAR.WhiteSpace.ScopeClosingBrace" />
 
-  <!-- Include documentation sniffs from WordPress-Docs. -->
+  <!-- Check block comments for conformity. -->
   <rule ref="Squiz.Commenting.BlockComment">
     <!-- We do not like empty lines after block comments. -->
     <exclude name="Squiz.Commenting.BlockComment.NoEmptyLineAfter" />
     <!-- Allow for /* translators: ... */ comments. -->
     <exclude name="Squiz.Commenting.BlockComment.SingleLine" />
-    <!-- Uses spaces for indentation. -->
+    <!-- These sniff codes use spaces for indentation. -->
     <exclude name="Squiz.Commenting.BlockComment.FirstLineIndent" />
     <exclude name="Squiz.Commenting.BlockComment.LineIndent" />
     <exclude name="Squiz.Commenting.BlockComment.LastLineIndent" />
   </rule>
+  <!-- Check class comments for conformity. -->
   <rule ref="Squiz.Commenting.ClassComment" />
+  <!-- Check block comment alignment. -->
   <rule ref="Squiz.Commenting.DocCommentAlignment" />
+  <!-- Enforce explanatory comments for empty catch statements. -->
   <rule ref="Squiz.Commenting.EmptyCatchComment" />
+  <!-- Check function comments for conformity. -->
   <rule ref="Squiz.Commenting.FunctionComment">
     <!-- We prefer shorthand int/bool over integer/boolean. -->
     <exclude name="Squiz.Commenting.FunctionComment.IncorrectParamVarName" />
@@ -135,7 +139,9 @@
     <exclude name="Squiz.Commenting.FunctionComment.ThrowsNoFullStop" />
     <exclude name="Squiz.Commenting.FunctionComment.ThrowsNotCapital" />
   </rule>
+  <!-- Enforce comments for @throws tags. -->
   <rule ref="Squiz.Commenting.FunctionCommentThrowTag" />
+  <!-- Check inline comments for conformity. -->
   <rule ref="Squiz.Commenting.InlineComment">
     <!-- Allow inline docblocks. -->
     <exclude name="Squiz.Commenting.InlineComment.DocBlock" />
@@ -144,7 +150,9 @@
     <!-- Allow "translators:" comments. -->
     <exclude name="Squiz.Commenting.InlineComment.NotCapital" />
   </rule>
+  <!-- Disallow post-statement comments. -->
   <rule ref="Squiz.Commenting.PostStatementComment" />
+  <!-- Check variable comments for conformity. -->
   <rule ref="Squiz.Commenting.VariableComment">
     <!-- We prefer shorthand int/bool over integer/boolean. -->
     <exclude name="Squiz.Commenting.VariableComment.IncorrectVarType" />

From 65e70d2c98cd82f61c5b7d7381f74b4e1fa024fe Mon Sep 17 00:00:00 2001
From: Jay McPartland <jay@bigbite.net>
Date: Fri, 7 Mar 2025 15:51:59 +0000
Subject: [PATCH 3/3] Exclude rule property for block comments

---
 BigBite/ruleset.xml | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/BigBite/ruleset.xml b/BigBite/ruleset.xml
index 017769f..822836d 100644
--- a/BigBite/ruleset.xml
+++ b/BigBite/ruleset.xml
@@ -122,6 +122,8 @@
     <exclude name="Squiz.Commenting.BlockComment.FirstLineIndent" />
     <exclude name="Squiz.Commenting.BlockComment.LineIndent" />
     <exclude name="Squiz.Commenting.BlockComment.LastLineIndent" />
+    <!-- We expect block comments to start with /** (instead of /*). -->
+    <exclude name="Squiz.Commenting.BlockComment.WrongStart" />
   </rule>
   <!-- Check class comments for conformity. -->
   <rule ref="Squiz.Commenting.ClassComment" />