fix: FunctionComment sniff docs and unit test.

- Fixed the sniff docs with the new changes regarding the nested functions being ignored, and the void magic methods.

- Fixed the unit test to include a test on the `__construct` magic method for the `VoidReturnTagFound` violation.

Author: yCodeTech

yCodeTech/Docs/Commenting/FunctionCommentStandard.xml

@@ -5,7 +5,7 @@
 
         This rule enforces:
 
-        1. Functions with `non-void` return types (`string`, `bool`, etc.) must have a `@return` tag.
+        1. Functions with `non-void` return types (`string`, `bool`, etc.) must have a `@return` tag (nested anonymous function and closure returns will be ignored).
         2. Functions with `void` return types must NOT have `@return` tags, except generator functions.
         3. Generator functions must have a `@return` tag.
 
@@ -14,6 +14,7 @@
         - 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.
+        - Most magic methods are exempt from having `@return` tags removed, except those that return `void`: `__construct`, `__destruct`, `__clone`, `__set`, `__unset`, `__wakeup`, and `__unserialize`.
         - 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.
         
         ---
@@ -78,6 +79,31 @@ public function processData(array $data): void
         </code>
     </code_comparison>
 
+    <code_comparison>
+        <code title="✔️ Valid: No @return for void constructor magic method">
+            <![CDATA[
+/**
+ * Constructor method.<em>
+</em> */
+public function __construct()
+{
+}
+            ]]>
+        </code>
+        <code title="❌ Invalid: @return tag on void constructor magic method">
+            <![CDATA[
+/**
+ * Constructor method.
+ *
+ * <em>@return void</em>
+ */
+public function __construct()
+{
+}
+            ]]>
+        </code>
+    </code_comparison>
+
     <code_comparison>
         <code title="✔️ Valid: @return tag for generator function">
             <![CDATA[

yCodeTech/Tests/Commenting/FunctionCommentUnitTest.inc

@@ -28,6 +28,14 @@ class TestClass
         echo $message;
     }
 
+    /**
+     * Constructor method with a `@return` tag.
+     *
+     * @return void
+     */
+    public function __construct() {
+    }
+
     /**
      * Generator function missing iterable @return tag
      *

yCodeTech/Tests/Commenting/FunctionCommentUnitTest.inc.fixed

@@ -28,6 +28,12 @@ class TestClass
         echo $message;
     }
 
+    /**
+     * Constructor method with a `@return` tag.
+     */
+    public function __construct() {
+    }
+
     /**
      * Generator function missing iterable @return tag
      *

yCodeTech/Tests/Commenting/FunctionCommentUnitTest.php

@@ -32,8 +32,9 @@ public function getErrorList()
         return [
             14 => 1,  // Function missing @return tag
             24 => 1,  // Void function with a @return tag
-            36 => 1,  // Generator function missing @return tag (should get iterable)
-            48 => 1,  // Generator function with yield from missing @return tag
+            34 => 1,  // Void constructor magic method with a @return tag
+            44 => 1,  // Generator function missing @return tag (should get iterable)
+            56 => 1,  // Generator function with yield from missing @return tag
         ];
     }
 
@@ -49,4 +50,4 @@ public function getWarningList()
     {
         return [];
     }
-}
+}