From b36cce353faad28613d6449a73b73c5e3d5ce4d8 Mon Sep 17 00:00:00 2001
From: Klaus Purer <klaus.purer@protonmail.ch>
Date: Sun, 25 May 2025 11:47:27 +0200
Subject: [PATCH] fix(FunctionComment): Allow complex array type for return
 comment (#3526462)

---
 .../Sniffs/Commenting/FunctionCommentSniff.php      |  7 ++++++-
 tests/Drupal/good/good.php                          | 13 +++++++++++++
 2 files changed, 19 insertions(+), 1 deletion(-)

diff --git a/coder_sniffer/Drupal/Sniffs/Commenting/FunctionCommentSniff.php b/coder_sniffer/Drupal/Sniffs/Commenting/FunctionCommentSniff.php
index 95f43253..a8536d57 100644
--- a/coder_sniffer/Drupal/Sniffs/Commenting/FunctionCommentSniff.php
+++ b/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;
                     }
                 }
diff --git a/tests/Drupal/good/good.php b/tests/Drupal/good/good.php
index daa9c27c..3ef195e2 100644
--- a/tests/Drupal/good/good.php
+++ b/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();
+}