[PEAR\Commenting\FunctionComment] Improve check for special method and add an option

src/Standards/PEAR/Sniffs/Commenting/FunctionCommentSniff.php

@@ -25,6 +25,16 @@ class FunctionCommentSniff implements Sniff
      */
     public $minimumVisibility = 'private';
 
+    /**
+     * Array of methods which do not require a return type.
+     *
+     * @var array
+     */
+    public $specialMethods = [
+        '__construct',
+        '__destruct',
+    ];
+
 
     /**
      * Returns an array of tokens this test wants to listen for.
@@ -135,7 +145,7 @@ protected function processReturn(File $phpcsFile, $stackPtr, $commentStart)
 
         // Skip constructor and destructor.
         $methodName      = $phpcsFile->getDeclarationName($stackPtr);
-        $isSpecialMethod = ($methodName === '__construct' || $methodName === '__destruct');
+        $isSpecialMethod = in_array($methodName,  $this->specialMethods, true);
 
         $return = null;
         foreach ($tokens[$commentStart]['comment_tags'] as $tag) {
@@ -150,17 +160,17 @@ protected function processReturn(File $phpcsFile, $stackPtr, $commentStart)
             }
         }
 
-        if ($isSpecialMethod === true) {
-            return;
-        }
-
         if ($return !== null) {
             $content = $tokens[($return + 2)]['content'];
             if (empty($content) === true || $tokens[($return + 2)]['code'] !== T_DOC_COMMENT_STRING) {
                 $error = 'Return type missing for @return tag in function comment';
                 $phpcsFile->addError($error, $return, 'MissingReturnType');
             }
         } else {
+            if ($isSpecialMethod === true) {
+                return;
+            }
+
             $error = 'Missing @return tag in function comment';
             $phpcsFile->addError($error, $tokens[$commentStart]['comment_closer'], 'MissingReturn');
         }//end if

src/Standards/PEAR/Tests/Commenting/FunctionCommentUnitTest.inc

@@ -398,3 +398,34 @@ private function setTranslator4($a, &$b): void
 {
     $this->translator = $translator;
 }
+
+class Bar {
+    /**
+     * The PHP5 constructor
+     *
+     * @return
+     */
+    public function __construct() {
+
+    }
+}
+
+// phpcs:set PEAR.Commenting.FunctionComment specialMethods[]
+class Bar {
+    /**
+     * The PHP5 constructor
+     */
+    public function __construct() {
+
+    }
+}
+
+// phpcs:set PEAR.Commenting.FunctionComment specialMethods[] ignored
+/**
+ * Should be ok
+ */
+public function ignored() {
+
+}
+
+// phpcs:set PEAR.Commenting.FunctionComment specialMethods[] __construct,__destruct

src/Standards/PEAR/Tests/Commenting/FunctionCommentUnitTest.inc.fixed

@@ -398,3 +398,34 @@ private function setTranslator4($a, &$b): void
 {
     $this->translator = $translator;
 }
+
+class Bar {
+    /**
+     * The PHP5 constructor
+     *
+     * @return
+     */
+    public function __construct() {
+
+    }
+}
+
+// phpcs:set PEAR.Commenting.FunctionComment specialMethods[]
+class Bar {
+    /**
+     * The PHP5 constructor
+     */
+    public function __construct() {
+
+    }
+}
+
+// phpcs:set PEAR.Commenting.FunctionComment specialMethods[] ignored
+/**
+ * Should be ok
+ */
+public function ignored() {
+
+}
+
+// phpcs:set PEAR.Commenting.FunctionComment specialMethods[] __construct,__destruct

src/Standards/PEAR/Tests/Commenting/FunctionCommentUnitTest.php

@@ -68,6 +68,8 @@ public function getErrorList()
             361 => 1,
             363 => 1,
             364 => 1,
+            406 => 1,
+            417 => 1,
         ];
 
     }//end getErrorList()

src/Standards/Squiz/Sniffs/Commenting/FunctionCommentSniff.php

@@ -67,10 +67,7 @@ protected function processReturn(File $phpcsFile, $stackPtr, $commentStart)
 
         // Skip constructor and destructor.
         $methodName      = $phpcsFile->getDeclarationName($stackPtr);
-        $isSpecialMethod = ($methodName === '__construct' || $methodName === '__destruct');
-        if ($isSpecialMethod === true) {
-            return;
-        }
+        $isSpecialMethod = in_array($methodName,  $this->specialMethods, true);
 
         if ($return !== null) {
             $content = $tokens[($return + 2)]['content'];
@@ -181,6 +178,10 @@ protected function processReturn(File $phpcsFile, $stackPtr, $commentStart)
                 }//end if
             }//end if
         } else {
+            if ($isSpecialMethod === true) {
+                return;
+            }
+
             $error = 'Missing @return tag in function comment';
             $phpcsFile->addError($error, $tokens[$commentStart]['comment_closer'], 'MissingReturn');
         }//end if

src/Standards/Squiz/Tests/Commenting/FunctionCommentUnitTest.inc

@@ -666,7 +666,7 @@ class Baz {
  * Test
  *
  * @return void
- * @throws E 
+ * @throws E
  */
 function myFunction() {}
 
@@ -1021,3 +1021,23 @@ public function foo($a, $b) {}
  * @return mixed
  */
 public function foo(mixed $a): mixed {}
+
+// phpcs:set Squiz.Commenting.FunctionComment specialMethods[]
+class Bar {
+    /**
+     * The PHP5 constructor
+     */
+    public function __construct() {
+
+    }
+}
+
+// phpcs:set Squiz.Commenting.FunctionComment specialMethods[] ignored
+/**
+ * Should be ok
+ */
+public function ignored() {
+
+}
+
+// phpcs:set Squiz.Commenting.FunctionComment specialMethods[] __construct,__destruct

src/Standards/Squiz/Tests/Commenting/FunctionCommentUnitTest.inc.fixed

@@ -666,7 +666,7 @@ class Baz {
  * Test
  *
  * @return void
- * @throws E 
+ * @throws E
  */
 function myFunction() {}
 
@@ -1021,3 +1021,23 @@ public function foo($a, $b) {}
  * @return mixed
  */
 public function foo(mixed $a): mixed {}
+
+// phpcs:set Squiz.Commenting.FunctionComment specialMethods[]
+class Bar {
+    /**
+     * The PHP5 constructor
+     */
+    public function __construct() {
+
+    }
+}
+
+// phpcs:set Squiz.Commenting.FunctionComment specialMethods[] ignored
+/**
+ * Should be ok
+ */
+public function ignored() {
+
+}
+
+// phpcs:set Squiz.Commenting.FunctionComment specialMethods[] __construct,__destruct

src/Standards/Squiz/Tests/Commenting/FunctionCommentUnitTest.php

@@ -115,6 +115,7 @@ public function getErrorList()
             997  => 1,
             1004 => 2,
             1006 => 1,
+            1029 => 1,
         ];
 
         // Scalar type hints only work from PHP 7 onwards.