From 8eeba2e06257d9de7afd23772afda3865d955caa Mon Sep 17 00:00:00 2001
From: Jay McPartland <jay@bigbite.net>
Date: Fri, 21 Mar 2025 15:14:25 +0000
Subject: [PATCH 1/2] Split documentation standards out into own ruleset

---
 BigBite-Docs/ruleset.xml | 63 ++++++++++++++++++++++++++++++++++++++++
 BigBite/ruleset.xml      | 59 +++----------------------------------
 2 files changed, 67 insertions(+), 55 deletions(-)
 create mode 100644 BigBite-Docs/ruleset.xml

diff --git a/BigBite-Docs/ruleset.xml b/BigBite-Docs/ruleset.xml
new file mode 100644
index 0000000..8d42e25
--- /dev/null
+++ b/BigBite-Docs/ruleset.xml
@@ -0,0 +1,63 @@
+<?xml version="1.0"?>
+<ruleset name="BigBite-Docs" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/squizlabs/PHP_CodeSniffer/master/phpcs.xsd">
+  <!-- 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" />
+  </rule>
+  <!-- Warn when there's todo/fixme notations -->
+  <rule ref="Generic.Commenting.Todo" />
+  <rule ref="Generic.Commenting.Fixme" />
+  <!-- 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" />
+    <!-- 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" />
+    <!-- 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" />
+  <!-- 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" />
+    <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>
+  <!-- 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" />
+    <!-- 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>
+  <!-- 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" />
+  </rule>
+  <!-- Validate format of file headers (when present). -->
+  <rule ref="PSR12.Files.FileHeader">
+    <!-- Disable assumption that the first comment in a file is a file comment. -->
+    <exclude name="PSR12.Files.FileHeader.SpacingAfterBlock" />
+  </rule>
+</ruleset>
diff --git a/BigBite/ruleset.xml b/BigBite/ruleset.xml
index 3d2b31f..7a8912d 100644
--- a/BigBite/ruleset.xml
+++ b/BigBite/ruleset.xml
@@ -68,6 +68,9 @@
   <!-- Use all of WP VIP's ruleset. -->
   <rule ref="WordPress-VIP-Go" />
 
+  <!-- Use Big Bite's code documentation ruleset. -->
+  <rule ref="BigBite-Docs" />
+
   <!-- ################ -->
   <!-- Additional rules -->
   <!-- ################ -->
@@ -98,14 +101,7 @@
     <exclude name="Generic.CodeAnalysis.UnusedFunctionParameter.FoundInImplementedInterfaceAfterLastUsed" />
     <exclude name="Generic.CodeAnalysis.UnusedFunctionParameter.FoundInImplementedInterfaceBeforeLastUsed" />
   </rule>
-  <!-- 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" />
-  </rule>
-  <!-- Warn when there's todo/fixme notations -->
-  <rule ref="Generic.Commenting.Todo" />
-  <rule ref="Generic.Commenting.Fixme" />
+
   <!-- See: McCabe's Cyclomatic Complexity -->
   <rule ref="Generic.Metrics.CyclomaticComplexity" />
   <!-- Limit nesting levels to 5. -->
@@ -125,53 +121,6 @@
   <!-- Check that the closing braces of scopes are aligned correctly. -->
   <rule ref="PEAR.WhiteSpace.ScopeClosingBrace" />
 
-  <!-- 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" />
-    <!-- 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" />
-    <!-- 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" />
-  <!-- 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" />
-    <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>
-  <!-- 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" />
-    <!-- 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>
-  <!-- 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" />
-  </rule>
   <!-- Force debug output function calls to error. -->
   <rule ref="Squiz.PHP.DiscouragedFunctions">
     <properties>

From d6f6436f41f96fde6cdc7c143f031d69fc41e9a2 Mon Sep 17 00:00:00 2001
From: Jay McPartland <jay@bigbite.net>
Date: Fri, 26 Sep 2025 14:49:55 +0100
Subject: [PATCH 2/2] Update Schema locations

---
 BigBite-Docs/ruleset.xml | 2 +-
 BigBite/ruleset.xml      | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/BigBite-Docs/ruleset.xml b/BigBite-Docs/ruleset.xml
index 8d42e25..1575a6a 100644
--- a/BigBite-Docs/ruleset.xml
+++ b/BigBite-Docs/ruleset.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0"?>
-<ruleset name="BigBite-Docs" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/squizlabs/PHP_CodeSniffer/master/phpcs.xsd">
+<ruleset name="BigBite-Docs" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://schema.phpcodesniffer.com/phpcs.xsd">
   <!-- Check block comments for conformity.. -->
   <rule ref="Generic.Commenting.DocComment">
     <!-- Allow other tags to come before @param comments - @see, @link, etc. -->
diff --git a/BigBite/ruleset.xml b/BigBite/ruleset.xml
index 7a8912d..38f2403 100644
--- a/BigBite/ruleset.xml
+++ b/BigBite/ruleset.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0"?>
-<ruleset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="BigBite" namespace="BigBiteCS\BigBite" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/squizlabs/PHP_CodeSniffer/master/phpcs.xsd">
+<ruleset xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" name="BigBite" namespace="BigBiteCS\BigBite" xsi:noNamespaceSchemaLocation="https://schema.phpcodesniffer.com/phpcs.xsd">
   <config name="encoding" value="utf-8" />
   <config name="testVersion" value="7.4-" />