From 9141b682dca42962b98e0d3aa9204c5dbb08414b Mon Sep 17 00:00:00 2001
From: wuchen90 <wu.chen@agriconomie.com>
Date: Fri, 17 Jan 2025 17:42:05 +0100
Subject: [PATCH] [PropertyInfo] Get short description from promoted properties
 in PhpDocExtractor

---
 .../Component/PropertyInfo/CHANGELOG.md       |  1 +
 .../Extractor/PhpDocExtractor.php             | 12 +++++++++
 .../Tests/Extractor/PhpDocExtractorTest.php   | 18 +++++++++++++
 .../PromotedPropertiesWithDocBlock.php        | 27 +++++++++++++++++++
 4 files changed, 58 insertions(+)
 create mode 100644 src/Symfony/Component/PropertyInfo/Tests/Fixtures/Extractor/PromotedPropertiesWithDocBlock.php

diff --git a/src/Symfony/Component/PropertyInfo/CHANGELOG.md b/src/Symfony/Component/PropertyInfo/CHANGELOG.md
index 78803e270751f..7960155943e14 100644
--- a/src/Symfony/Component/PropertyInfo/CHANGELOG.md
+++ b/src/Symfony/Component/PropertyInfo/CHANGELOG.md
@@ -6,6 +6,7 @@ CHANGELOG
 
  * Add support for `non-positive-int`, `non-negative-int` and `non-zero-int` PHPStan types to `PhpStanExtractor`
  * Add `PropertyDescriptionExtractorInterface` to `PhpStanExtractor`
+ * Add support for getting description from constructor with promoted arguments to `PhpDocExtractor`
 
 7.1
 ---
diff --git a/src/Symfony/Component/PropertyInfo/Extractor/PhpDocExtractor.php b/src/Symfony/Component/PropertyInfo/Extractor/PhpDocExtractor.php
index ec44fcadd83c3..1bda7247e52ef 100644
--- a/src/Symfony/Component/PropertyInfo/Extractor/PhpDocExtractor.php
+++ b/src/Symfony/Component/PropertyInfo/Extractor/PhpDocExtractor.php
@@ -102,6 +102,18 @@ public function getShortDescription(string $class, string $property, array $cont
             }
         }
 
+        foreach ($docBlock->getTagsByName('param') as $param) {
+            if (!$param instanceof DocBlock\Tags\Param) {
+                continue;
+            }
+
+            $paramDescription = $param->getDescription()?->render();
+
+            if (null !== $paramDescription && '' !== $paramDescription) {
+                return $paramDescription;
+            }
+        }
+
         return null;
     }
 
diff --git a/src/Symfony/Component/PropertyInfo/Tests/Extractor/PhpDocExtractorTest.php b/src/Symfony/Component/PropertyInfo/Tests/Extractor/PhpDocExtractorTest.php
index 003011f87bf13..fbe71841ca6a0 100644
--- a/src/Symfony/Component/PropertyInfo/Tests/Extractor/PhpDocExtractorTest.php
+++ b/src/Symfony/Component/PropertyInfo/Tests/Extractor/PhpDocExtractorTest.php
@@ -19,6 +19,7 @@
 use Symfony\Component\PropertyInfo\Tests\Fixtures\Dummy;
 use Symfony\Component\PropertyInfo\Tests\Fixtures\DummyCollection;
 use Symfony\Component\PropertyInfo\Tests\Fixtures\InvalidDummy;
+use Symfony\Component\PropertyInfo\Tests\Fixtures\Extractor\PromotedPropertiesWithDocBlock;
 use Symfony\Component\PropertyInfo\Tests\Fixtures\ParentDummy;
 use Symfony\Component\PropertyInfo\Tests\Fixtures\Php80Dummy;
 use Symfony\Component\PropertyInfo\Tests\Fixtures\PseudoTypeDummy;
@@ -889,6 +890,23 @@ public static function promotedPropertyProvider(): iterable
         yield ['promoted', null];
         yield ['promotedAndMutated', Type::string()];
     }
+
+    /**
+     * @dataProvider provideGetShortDescriptionOnPromotedPropertyTestCases
+     */
+    public function testGetShortDescriptionOnPromotedProperty(string $class, string $property, ?string $description)
+    {
+        $this->assertSame($description, $this->extractor->getShortDescription($class, $property));
+    }
+
+    public static function provideGetShortDescriptionOnPromotedPropertyTestCases(): array
+    {
+        return [
+            [PromotedPropertiesWithDocBlock::class, 'foo', 'Just a foo property'],
+            [PromotedPropertiesWithDocBlock::class, 'bar', 'A phpdoc without type'],
+            'Inlined phpdoc with @var is not compatible with the one above constructor' => [PromotedPropertiesWithDocBlock::class, 'baz', null],
+        ];
+    }
 }
 
 class EmptyDocBlock
diff --git a/src/Symfony/Component/PropertyInfo/Tests/Fixtures/Extractor/PromotedPropertiesWithDocBlock.php b/src/Symfony/Component/PropertyInfo/Tests/Fixtures/Extractor/PromotedPropertiesWithDocBlock.php
new file mode 100644
index 0000000000000..2090fd6fcb245
--- /dev/null
+++ b/src/Symfony/Component/PropertyInfo/Tests/Fixtures/Extractor/PromotedPropertiesWithDocBlock.php
@@ -0,0 +1,27 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Component\PropertyInfo\Tests\Fixtures\Extractor;
+
+class PromotedPropertiesWithDocBlock
+{
+    /**
+     * @param string $foo Just a foo property
+     * @param $bar A phpdoc without type
+     */
+    public function __construct(
+        public string $foo,
+        public int $bar,
+        /** @var string $baz This phpdoc isn't compatible with the one above this method, thus it won't appear */
+        public string $baz,
+    ) {
+    }
+}