docs: change formatting and wording of the sniffs documentation.

Author: yCodeTech

yCodeTech/Docs/Commenting/DocblockFormatStandard.xml

@@ -3,7 +3,7 @@
         <![CDATA[
         Enforces proper spacing and formatting in docblocks:
         1. All docblock tags must have exactly `1 space` between each element.
-        2. Type and variable in any tags must have exactly `1 space` between them.
+        2. The type and variable in any tag must be separated by a `space`.
         3. `@return` tags must be preceded by exactly `1 empty line`.
 
         ]]>

yCodeTech/Docs/Commenting/FunctionCommentStandard.xml

@@ -1,19 +1,19 @@
 <documentation title="Function Comment">
     <standard>
         <![CDATA[
-        Non-void returning functions must have a @return docblock tag.
+        Functions that return a value must have a `@return` docblock tag.
 
         This rule enforces:
 
-        1. Functions with non-void return types (string, bool, etc.) must have a `@return` tag.
-        2. Functions with void return types must NOT have `@return` tags, except generator functions.
-        3. Generator functions must have a `@return` tag with type iterable.
+        1. Functions with `non-void` return types (`string`, `bool`, etc.) must have a `@return` tag.
+        2. Functions with `void` return types must NOT have `@return` tags, except generator functions.
+        3. Generator functions must have a `@return` tag.
 
         Notes:
 
         - Both typed and untyped functions are checked.
         - Return types can be declared or inferred from function signature.
-        - Magic methods (e.g. __construct, __get, etc.) are exempt from requiring @return tags.
+        - Magic methods (e.g. `__construct`, `__get`, etc.) are exempt from requiring `@return` tags.
         - Fixing `@return` tags will have the type `mixed`, and generator functions will have the type `iterable`; these should then be edited manually to specific types.
         
         ---
@@ -32,7 +32,6 @@
  */
 public function formatString(string $input): string
 {
-    return strtoupper($input);
 }
             ]]>
         </code>
@@ -45,7 +44,6 @@ public function formatString(string $input): string
 </em> */
 public function formatString(string $input): string
 {
-    return strtoupper($input);
 }
             ]]>
         </code>
@@ -61,7 +59,6 @@ public function formatString(string $input): string
 </em> */
 public function processData(array $data): void
 {
-    // Process data
 }
             ]]>
         </code>
@@ -76,7 +73,6 @@ public function processData(array $data): void
  */
 public function processData(array $data): void
 {
-    // Process data
 }
             ]]>
         </code>

yCodeTech/Docs/Types/DisallowTypeLongNamesStandard.xml

@@ -11,7 +11,7 @@
         Applies to:
 
         1. Regular docblock tags that contain types (`@param`, `@return`, `@var`, `@property`, `@method`) and any others that contain these regular tags (`@property-read`, `@property-write`, `@phpstan-*`, `@psalm-*`, etc.)
-        2. Docblock generic types: `array<integer, boolean>` → `array<int, bool>`, `array<boolean>` → `array<bool>`, `Collection<integer>` → `Collection<int>`, etc.
+        2. Docblock generic types: array<`integer`, `boolean`> → array<`int`, `bool`>, array<`boolean`> → array<`bool`>, Collection<`integer`> → Collection<`int`>, etc.
         3. Function/method/closure parameter and return type declarations
         4. Class property type declarations
         5. Nullable and union types: `?boolean` → `?bool`, `?integer` → `?int`, `boolean|string` → `bool|string`, `integer|string` → `int|string`
@@ -24,6 +24,7 @@
 /**
  * @param <em>bool</em> $isValid
  * @psalm-param <em>bool</em> $isValid
+ *
  * @return <em>int</em>
  */
             ]]>
@@ -33,6 +34,7 @@
 /**
  * @param <em>boolean</em> $isValid
  * @psalm-param <em>boolean</em> $isValid
+ *
  * @return <em>integer</em>
  */
             ]]>
@@ -45,7 +47,7 @@
  * @param Collection<<em>int</em>> $numbers
  * @param Map<string, <em>bool</em>> $settings
  * @param array<string, <em>int</em>> $counts
- * @param array< <em>bool</em>, <em>int</em>> $counts
+ * @param array<<em>bool</em>, <em>int</em>> $counts
  */
             ]]>
         </code>
@@ -55,7 +57,7 @@
  * @param Collection<<em>integer</em>> $numbers
  * @param Map<string, <em>boolean</em>> $settings
  * @param array<string, <em>integer</em>> $counts
- * @param array< <em>boolean</em>, <em>integer</em>> $counts
+ * @param array<<em>boolean</em>, <em>integer</em>> $counts
  */
             ]]>
         </code>
@@ -80,21 +82,15 @@ protected <em>integer</em> $userCount;
             <![CDATA[
 function foo(<em>bool</em> $flag): <em>int</em> {
     $callback = function(<em>bool</em> $isValid): <em>int</em> {
-        return $isValid ? 10 : 5;
     };
-    
-    return $callback($flag);
 }
             ]]>
         </code>
         <code title="❌ Invalid: Long name function/method/closure types">
             <![CDATA[
 function foo(<em>boolean</em> $flag): <em>integer</em> {
     $callback = function(<em>boolean</em> $isValid): <em>integer</em> {
-        return $isValid ? 10 : 5;
     };
-    
-    return $callback($flag);
 }
             ]]>
         </code>
@@ -103,14 +99,12 @@ function foo(<em>boolean</em> $flag): <em>integer</em> {
         <code title="✔️ Valid: Short name nullable and union types">
             <![CDATA[
 function foo(?<em>bool</em> $flag, <em>bool</em>|string $var): ?<em>int</em> {
-    return $flag ? 10 : null;
 }
             ]]>
         </code>
         <code title="❌ Invalid: Long name nullable and union types">
             <![CDATA[
 function foo(?<em>boolean</em> $flag, <em>boolean</em>|string $var): ?<em>integer</em> {
-    return $flag ? 10 : null;
 }
             ]]>
         </code>