fix(FunctionComment): Allow complex array type for return comment (#3526462) (pfrenssen#267)

Author: klausi

coder_sniffer/Drupal/Sniffs/Commenting/FunctionCommentSniff.php

@@ -258,13 +258,18 @@ protected function processReturn(File $phpcsFile, $stackPtr, $commentStart)
                 $typeNames      = explode('|', $returnType);
                 $suggestedNames = [];
                 $hasNull        = false;
+                // Do not check PHPStan types that contain any kind of brackets.
+                // See https://phpstan.org/writing-php-code/phpdoc-types#general-arrays .
+                $isPhpstanType = preg_match('/[<\[\{\(]/', $returnType) === 1;
                 foreach ($typeNames as $i => $typeName) {
                     if (strtolower($typeName) === 'null') {
                         $hasNull = true;
                     }
 
                     $suggestedName = $this->suggestType($typeName);
-                    if (in_array($suggestedName, $suggestedNames, true) === false) {
+                    if (in_array($suggestedName, $suggestedNames, true) === false
+                        || $isPhpstanType === true
+                    ) {
                         $suggestedNames[] = $suggestedName;
                     }
                 }

tests/Drupal/good/good.php

@@ -2047,3 +2047,16 @@ interface BreadcrumbBuilderInterface {
   public function applies(RouteMatchInterface $route_match /* , CacheableMetadata $cacheable_metadata */);
 
 }
+
+/**
+ * Test that nested array types are ok.
+ *
+ * @param array<array<scalar|null>|object|scalar|null> $param
+ *   A complex nested array type.
+ *
+ * @return array<array<scalar|null>|object|scalar|null>
+ *   An array of results.
+ */
+function pdo_weird_return_type($param) {
+  return pdo();
+}