fix: void magic methods should be flagged if they have @return tag.

If void magic methods have a `@return` tag, they weren't being flagged because all magic methods were being skipped.

Fixed by introducing a list of void magic methods which allows them to be processed, while all other magic methods will be skipped.

Added:

- Added `shouldProcessMagicMethod` method to define the array of void magic methods, and determine if the current function is within the array.

- Added new test functions in both `TestFile`s.

Changed:
- Changed the `VoidReturnTagFound` violation error message to include the function name too.

- Changed readme to document the void magic methods.

Author: yCodeTech

README.md

@@ -210,14 +210,25 @@ Functions that return a value must have a `@return` docblock tag (nested anonymo
     <td>Functions with <code>void</code> return types must NOT have <code>@return</code> tags, except generator functions.
     </td>
     <td>✔️</td>
-    <td></td>
-  </tr>
-  <tr>
-    <td>Generator functions must have a <code>@return</code> tag.
-    </td>
-    <td>✔️</td>
     <td>
 
+-   Most magic methods are exempt, except for those that return `void`:
+<code>\_\_construct</code>, 
+<code>\_\_destruct</code>, 
+<code>\_\_clone</code>, 
+<code>\_\_set</code>, 
+<code>\_\_unset</code>, 
+<code>\_\_wakeup</code>, and
+<code>\_\_unserialize</code>.
+
+  </td>
+</tr>
+<tr>
+  <td>Generator functions must have a <code>@return</code> tag.
+  </td>
+  <td>✔️</td>
+  <td>
+
 - Fixes with an <code>iterable</code> return type.
 
 </td>

test_utils/TestFile.php

@@ -365,6 +365,42 @@ public function testImplicitVoidFunctionWithDocblockReturn($message)
         echo $message;
     }
 
+    /*****************************************
+     * VOID MAGIC METHODS WITH @RETURN TESTS *
+     *****************************************/
+
+    /**
+     * Construct magic method with unnecessary `@return void` tag (should be flagged).
+     *
+     * The following should be fixed:
+     * - The `@return` tag should be removed.
+     *
+     * @return void
+     */
+    public function __construct() {
+    }
+
+    /**
+     * Destruct magic method with unnecessary `@return void` tag (should be flagged).
+     *
+     * The following should be fixed:
+     * - The `@return` tag should be removed.
+     *
+     * @return void
+     */
+    public function __destruct() {
+    }
+
+    /**
+     * Set magic method with unnecessary `@return void` tag (should be flagged).
+     *
+     * The following should be fixed:
+     * - The `@return` tag should be removed.
+     *
+     * @return void
+     */
+    public function __set($name, $value) {
+    }
 
     /************************************
      * ALL OTHER @ TAGS FORMATTING TEST *

test_utils/TestFile_WithErrors_DoNotFix.php

@@ -365,6 +365,42 @@ public function testImplicitVoidFunctionWithDocblockReturn($message)
         echo $message;
     }
 
+    /*****************************************
+     * VOID MAGIC METHODS WITH @RETURN TESTS *
+     *****************************************/
+
+    /**
+     * Construct magic method with unnecessary `@return void` tag (should be flagged).
+     *
+     * The following should be fixed:
+     * - The `@return` tag should be removed.
+     *
+     * @return void
+     */
+    public function __construct() {
+    }
+
+    /**
+     * Destruct magic method with unnecessary `@return void` tag (should be flagged).
+     *
+     * The following should be fixed:
+     * - The `@return` tag should be removed.
+     *
+     * @return void
+     */
+    public function __destruct() {
+    }
+
+    /**
+     * Set magic method with unnecessary `@return void` tag (should be flagged).
+     *
+     * The following should be fixed:
+     * - The `@return` tag should be removed.
+     *
+     * @return void
+     */
+    public function __set($name, $value) {
+    }
 
     /************************************
      * ALL OTHER @ TAGS FORMATTING TEST *

yCodeTech/Sniffs/Commenting/FunctionCommentSniff.php

@@ -50,11 +50,9 @@ public function process(File $phpcsFile, $stackPtr)
             return;
         }
 
-        // Skip magic methods and constructors/destructors
+        // Get the function name for later processing
         $functionName = $tokens[$namePtr]['content'];
-        if (substr($functionName, 0, 2) === '__') {
-            return;
-        }
+        $isMagicMethod = substr($functionName, 0, 2) === '__';
 
         // Find the docblock for this function
         $commentEnd = $phpcsFile->findPrevious(T_DOC_COMMENT_CLOSE_TAG, ($stackPtr - 1));
@@ -90,6 +88,11 @@ public function process(File $phpcsFile, $stackPtr)
             }
         }
 
+        // Skip magic methods unless they are void magic methods that should be processed
+        if ($isMagicMethod && !$this->shouldProcessMagicMethod($functionName)) {
+            return;
+        }
+
         // Check if the function is a generator.
         // If so, then it should have @return tag with type iterable.
         $isGeneratorFunction = $this->isGeneratorFunction($phpcsFile, $stackPtr);
@@ -116,8 +119,8 @@ public function process(File $phpcsFile, $stackPtr)
             }
 
             if ($returnTagPtr !== false) {
-                $error = 'Void function should not have @return tag';
-                $fix = $phpcsFile->addFixableError($error, $returnTagPtr, 'VoidReturnTagFound');
+                $error = 'Void function (%s) should not have @return tag';
+                $fix = $phpcsFile->addFixableError($error, $returnTagPtr, 'VoidReturnTagFound', [$functionName]);
                 if ($fix === true) {
                     $this->removeReturnTag($phpcsFile, $returnTagPtr);
                 }
@@ -251,6 +254,32 @@ private function isReturnInNestedFunction(File $phpcsFile, $returnPtr, $function
         return false;
     }
 
+    /**
+     * Check if a magic method should be processed.
+     *
+     * Only void magic methods should be processed to flag unnecessary @return void tags.
+     * Magic methods that return values should be skipped entirely.
+     *
+     * @param string $functionName The name of the function.
+     *
+     * @return bool
+     */
+    private function shouldProcessMagicMethod($functionName)
+    {
+        // Magic methods that are typically void and should be processed for @return void violations
+        $voidMagicMethods = [
+            '__construct',
+            '__destruct',
+            '__clone',
+            '__set',
+            '__unset',
+            '__wakeup',
+            '__unserialize',
+        ];
+
+        return in_array($functionName, $voidMagicMethods, true);
+    }
+
     /**
      * Check if function is a generator function (contains yield statements).
      *