Added support for array multi line function comments

squizlabs · Oct 7, 2022 · 0fc0907 · 0fc0907
1 parent d7864cb
commit 0fc0907
Show file tree

Hide file tree

Showing 4 changed files with 101 additions and 7 deletions.
diff --git a/src/Standards/Squiz/Sniffs/Commenting/FunctionCommentSniff.php b/src/Standards/Squiz/Sniffs/Commenting/FunctionCommentSniff.php
@@ -306,24 +306,57 @@ protected function processParams(File $phpcsFile, $stackPtr, $commentStart)
             $varSpace     = 0;
             $comment      = '';
             $commentLines = [];
+            $isMultiLine = false;
             if ($tokens[($tag + 2)]['code'] === T_DOC_COMMENT_STRING) {
+                $content = $tokens[($tag + 2)]['content'];
+
+                $multiLineExtra = 0;
+
+                if (
+                    !$this->parenthesisClosed($content, '{', '}')
+                    || !$this->parenthesisClosed($content, '<', '>')
+                ) {
+                    $isMultiLine   = true;
+                    $content       = '';
+
+                    $i = $tag + 2;
+
+                    while (true) {
+                        if ($tokens[$i]['content'] === '@param') {
+                            break;
+                        }
+
+                        $content .= $tokens[$i]['content'];
+
+                        if (
+                            $this->parenthesisClosed($content, '{', '}')
+                            && $this->parenthesisClosed($content, '<', '>')
+                        ) {
+                            break;
+                        }
+
+                        $multiLineExtra++;
+                        $i++;
+                    }
+                }
+
                 $matches = [];
-                preg_match('/([^$&.]+)(?:((?:\.\.\.)?(?:\$|&)[^\s]+)(?:(\s+)(.*))?)?/', $tokens[($tag + 2)]['content'], $matches);
+                preg_match('/([^$&.]+)(?:((?:\.\.\.)?(?:\$|&)[^\s]+)(?:(\s+)(.*))?)?/', $content, $matches);
 
                 if (empty($matches) === false) {
                     $typeLen   = strlen($matches[1]);
                     $type      = trim($matches[1]);
                     $typeSpace = ($typeLen - strlen($type));
                     $typeLen   = strlen($type);
-                    if ($typeLen > $maxType) {
+                    if ($typeLen > $maxType && $isMultiLine === false) {
                         $maxType = $typeLen;
                     }
                 }
 
                 if (isset($matches[2]) === true) {
                     $var    = $matches[2];
                     $varLen = strlen($var);
-                    if ($varLen > $maxVar) {
+                    if ($varLen > $maxVar && $isMultiLine === false) {
                         $maxVar = $varLen;
                     }
 
@@ -332,7 +365,7 @@ protected function processParams(File $phpcsFile, $stackPtr, $commentStart)
                         $comment        = $matches[4];
                         $commentLines[] = [
                             'comment' => $comment,
-                            'token'   => ($tag + 2),
+                            'token'   => ($tag + 2 + $multiLineExtra),
                             'indent'  => $varSpace,
                         ];
 
@@ -343,7 +376,7 @@ protected function processParams(File $phpcsFile, $stackPtr, $commentStart)
                             $end = $tokens[$commentStart]['comment_closer'];
                         }
 
-                        for ($i = ($tag + 3); $i < $end; $i++) {
+                        for ($i = ($tag + 3 + $multiLineExtra); $i < $end; $i++) {
                             if ($tokens[$i]['code'] === T_DOC_COMMENT_STRING) {
                                 $indent = 0;
                                 if ($tokens[($i - 1)]['code'] === T_DOC_COMMENT_WHITESPACE) {
@@ -380,6 +413,7 @@ protected function processParams(File $phpcsFile, $stackPtr, $commentStart)
                 'commentLines' => $commentLines,
                 'type_space'   => $typeSpace,
                 'var_space'    => $varSpace,
+                'multi_line'   => $isMultiLine,
             ];
         }//end foreach
 
@@ -547,7 +581,9 @@ protected function processParams(File $phpcsFile, $stackPtr, $commentStart)
             $foundParams[] = $param['var'];
 
             // Check number of spaces after the type.
-            $this->checkSpacingAfterParamType($phpcsFile, $param, $maxType);
+            if ($param['multi_line'] === false) {
+                $this->checkSpacingAfterParamType($phpcsFile, $param, $maxType);
+            }
 
             // Make sure the param name is correct.
             if (isset($realParams[$pos]) === true) {
@@ -580,7 +616,9 @@ protected function processParams(File $phpcsFile, $stackPtr, $commentStart)
             }
 
             // Check number of spaces after the var name.
-            $this->checkSpacingAfterParamName($phpcsFile, $param, $maxVar);
+            if ($param['multi_line'] === false) {
+                $this->checkSpacingAfterParamName($phpcsFile, $param, $maxVar);
+            }
 
             // Param comments must start with a capital letter and end with a full stop.
             if (preg_match('/^(\p{Ll}|\P{L})/u', $param['comment']) === 1) {
@@ -764,5 +802,25 @@ protected function checkInheritdoc(File $phpcsFile, $stackPtr, $commentStart)
 
     }//end checkInheritdoc()
 
+    /**
+     * Determines wether string has the same number of open and close parenthesis.
+     *
+     * @param  string $string
+     * @param  string $openChar
+     * @param  string $closeChar
+     * @return bool
+     */
+    private function parenthesisClosed($string, $openChar, $closeChar)
+    {
+        if (stripos($string, $openChar) === false) {
+            return true;
+        }
+
+        $open  = substr_count($string, $openChar);
+        $close = substr_count($string, $closeChar);
+
+        return $open === $close;
+    }//end parenthesisClosed
+
 
 }//end class
diff --git a/src/Standards/Squiz/Tests/Commenting/FunctionCommentUnitTest.inc b/src/Standards/Squiz/Tests/Commenting/FunctionCommentUnitTest.inc
@@ -1046,3 +1046,20 @@ public function ignored() {
  * @return void
  * @throws Exception If any other error occurs. */
 function throwCommentOneLine() {}
+
+
+/**
+ * @param array{foo: int} $a A.
+ * @param array{x: int} $ccc C.
+ * @param array{xxxx: int} $dddd D.
+ * @param array<array{
+ *            foo: array{foo: int},
+ *            bar: int
+ *        }> $bb B.
+ *
+ * @return integer
+ */
+public function multiLineArray(array $a, array $ccc, array $dddd, array $bb)
+{
+    return 1;
+}//end multiLineArray()
diff --git a/src/Standards/Squiz/Tests/Commenting/FunctionCommentUnitTest.inc.fixed b/src/Standards/Squiz/Tests/Commenting/FunctionCommentUnitTest.inc.fixed
@@ -1046,3 +1046,20 @@ public function ignored() {
  * @return void
  * @throws Exception If any other error occurs. */
 function throwCommentOneLine() {}
+
+
+/**
+ * @param array{foo: int}  $a    A.
+ * @param array{x: int}    $ccc  C.
+ * @param array{xxxx: int} $dddd D.
+ * @param array<array{
+ *            foo: array{foo: int},
+ *            bar: int
+ *        }> $bb B.
+ *
+ * @return integer
+ */
+public function multiLineArray(array $a, array $ccc, array $dddd, array $bb)
+{
+    return 1;
+}//end multiLineArray()
diff --git a/src/Standards/Squiz/Tests/Commenting/FunctionCommentUnitTest.php b/src/Standards/Squiz/Tests/Commenting/FunctionCommentUnitTest.php
@@ -116,6 +116,8 @@ public function getErrorList()
             1004 => 2,
             1006 => 1,
             1029 => 1,
+            1052 => 2,
+            1053 => 2,
         ];
 
         // Scalar type hints only work from PHP 7 onwards.