Handle @param for variables passed by reference

squizlabs · Jun 7, 2023 · 10066e3 · 10066e3
1 parent d148feb
commit 10066e3
Show file tree

Hide file tree

Showing 4 changed files with 66 additions and 5 deletions.
diff --git a/src/Standards/Squiz/Sniffs/Commenting/FunctionCommentSniff.php b/src/Standards/Squiz/Sniffs/Commenting/FunctionCommentSniff.php
@@ -552,15 +552,32 @@ protected function processParams(File $phpcsFile, $stackPtr, $commentStart)
             // Make sure the param name is correct.
             if (isset($realParams[$pos]) === true) {
                 $realName = $realParams[$pos]['name'];
-                if ($realName !== $param['var']) {
+
+                if ($realParams[$pos]['pass_by_reference'] === true && $param['var'][0] === '&') {
+                    // When passed by reference, the variable name in $realParams does not have a leading '&'.
+                    // There is no guidance in PSR-19 to say if the docblock SHOULD or SHOULD NOT also have a
+                    // leading '&'. Therefore, this sniff remains agnostic in this case.
+                    $paramVarName = substr($param['var'], 1);
+
+                    // This fixes a false-positive with 'MissingParamTag'.
+                    $foundParams[count($foundParams) - 1] = $paramVarName;
+                } else {
+                    // When not passed by reference, the name should match exactly. If there is a stray
+                    // leading '&', then something has gone wrong and either the docblock or the
+                    // function / method signature needs to be changed. We can't auto-fix this as it's
+                    // not clear which of these two is wrong.
+                    $paramVarName = $param['var'];
+                }
+
+                if ($realName !== $paramVarName) {
                     $code = 'ParamNameNoMatch';
                     $data = [
-                        $param['var'],
+                        $paramVarName,
                         $realName,
                     ];
 
                     $error = 'Doc comment for parameter %s does not match ';
-                    if (strtolower($param['var']) === strtolower($realName)) {
+                    if (strtolower($paramVarName) === strtolower($realName)) {
                         $error .= 'case of ';
                         $code   = 'ParamNameNoCaseMatch';
                     }

diff --git a/src/Standards/Squiz/Tests/Commenting/FunctionCommentUnitTest.inc b/src/Standards/Squiz/Tests/Commenting/FunctionCommentUnitTest.inc
@@ -1046,3 +1046,24 @@ public function ignored() {
  * @return void
  * @throws Exception If any other error occurs. */
 function throwCommentOneLine() {}
+
+/**
+ * Test for passing variables by reference
+ *
+ * Note that PSR-19 makes no mention of variables passed by reference. This
+ * sniff treats the '&' as optional for parameters passed by reference, but
+ * forbidden for parameters which are not passed by reference.
+ *
+ * Because mismatches may be in either direction, we cannot auto-fix these.
+ *
+ * @param string $foo  A string passed in by reference.
+ * @param string &$bar A string passed in by reference.
+ * @param string $baz  A string NOT passed in by reference.
+ * @param string &$qux A string NOT passed in by reference.
+ *
+ * @return void
+ */
+public function variablesPassedByReference(&$foo, &$bar, $baz, $qux)
+{
+    return;
+}//end variablesPassedByReference()
diff --git a/src/Standards/Squiz/Tests/Commenting/FunctionCommentUnitTest.inc.fixed b/src/Standards/Squiz/Tests/Commenting/FunctionCommentUnitTest.inc.fixed
@@ -1046,3 +1046,24 @@ public function ignored() {
  * @return void
  * @throws Exception If any other error occurs. */
 function throwCommentOneLine() {}
+
+/**
+ * Test for passing variables by reference
+ *
+ * Note that PSR-19 makes no mention of variables passed by reference. This
+ * sniff treats the '&' as optional for parameters passed by reference, but
+ * forbidden for parameters which are not passed by reference.
+ *
+ * Because mismatches may be in either direction, we cannot auto-fix these.
+ *
+ * @param string $foo  A string passed in by reference.
+ * @param string &$bar A string passed in by reference.
+ * @param string $baz  A string NOT passed in by reference.
+ * @param string &$qux A string NOT passed in by reference.
+ *
+ * @return void
+ */
+public function variablesPassedByReference(&$foo, &$bar, $baz, $qux)
+{
+    return;
+}//end variablesPassedByReference()
diff --git a/src/Standards/Squiz/Tests/Commenting/FunctionCommentUnitTest.php b/src/Standards/Squiz/Tests/Commenting/FunctionCommentUnitTest.php
@@ -48,8 +48,7 @@ public function getErrorList()
             138  => 4,
             139  => 4,
             143  => 2,
-            152  => 1,
-            155  => 2,
+            155  => 1, // ParamCommentFullStop
             159  => 1,
             166  => 1,
             173  => 1,
@@ -116,6 +115,8 @@ public function getErrorList()
             1004 => 2,
             1006 => 1,
             1029 => 1,
+            1050 => 1, // MissingParamTag ('$qux' not documented)
+            1062 => 1, // ParamNameNoMatch ('&$qux' versus '$qux')
         ];
 
         // Scalar type hints only work from PHP 7 onwards.
@@ -131,6 +132,7 @@ public function getErrorList()
             $errors[575]  = 2;
             $errors[627]  = 1;
             $errors[1002] = 1;
+            $errors[1066] = 4; // ScalarTypeHintMissing
         } else {
             $errors[729] = 4;
             $errors[740] = 2;