[Backport #1998 to 5.x] Handle parameter dockblocks

src/Analysers/AttributeAnnotationFactory.php

@@ -95,7 +95,14 @@ public function build(\Reflector $reflector, Context $context): array
                                 } else {
                                     $instance->_context->property = $rp->getName();
                                 }
+                            } elseif ($instance instanceof OAT\Parameter) {
+                                if (method_exists($rp, 'getDocComment')) {
+                                    if ($comment = $rp->getDocComment()) {
+                                        $instance->_context->comment = $comment;
+                                    }
+                                }
                             }
+
                             $annotations[] = $instance;
                         }
                     }

src/Processors/AugmentParameters.php

@@ -136,12 +136,19 @@ protected function augmentOperationParameters(Analysis $analysis): void
             if (!Generator::isDefault($operation->parameters)) {
                 $tags = [];
                 $this->parseDocblock($operation->_context->comment, $tags);
-                $docblockParams = $tags['param'] ?? [];
+                $operationDocblockParams = $tags['param'] ?? [];
 
                 foreach ($operation->parameters as $parameter) {
                     if (Generator::isDefault($parameter->description)) {
-                        if (array_key_exists($parameter->name, $docblockParams)) {
-                            $details = $docblockParams[$parameter->name];
+                        $typeAndDescription = $this->parseVarLine((string) $parameter->_context->comment);
+                        if ($typeAndDescription['description']) {
+                            $parameter->description = trim($typeAndDescription['description']);
+                        }
+                    }
+
+                    if (Generator::isDefault($parameter->description)) {
+                        if (array_key_exists($parameter->name, $operationDocblockParams)) {
+                            $details = $operationDocblockParams[$parameter->name];
                             if ($details['description']) {
                                 $parameter->description = $details['description'];
                             }

src/Processors/Concerns/DocblockTrait.php

@@ -184,9 +184,13 @@ public function extractCommentDescription(string $content): string
     public function parseVarLine(?string $docblock): array
     {
         $comment = str_replace("\r\n", "\n", (string) $docblock);
-        $comment = preg_replace('/\*\/[ \t]*$/', '', $comment); // strip '*/'
+        $comment = preg_replace(['/[ \t]*\\/\*\*/', '/\*\/[ \t]*$/'], '', $comment); // '/**', '*/'
 
+<<<<<<< HEAD
         preg_match('/@var\s+(?<type>[^\s]+)([ \t])?(?<description>.+)?+$/im', $comment, $matches);
+=======
+        preg_match('/@var[ \t]+(?<type>[^\s]+)(?:[ \t]+\$(?<name>\w+))?(?:[ \t]+(?<description>.+))?$/im', (string) $comment, $matches);
+>>>>>>> 4b1ec56 (Prepare for parameter (`@var`) docblocks)
 
         $result = array_merge(
             ['type' => null, 'description' => null],

tests/Fixtures/PHP/DocblockAndTypehintTypes.php

@@ -195,6 +195,7 @@ public function paramMethod(
      * @param ?string[] $blah_values
      */
     public function blah(
+        /** @var string|null The blah */
         #[OAT\Property(example: 'My blah')]
         ?string $blah,
         #[OAT\Property(nullable: true, items: new OAT\Items(type: 'string', example: 'hello'))]

tests/Fixtures/Scratch/Docblocks.php

@@ -109,7 +109,9 @@ class DocblocksEndpoint
     )]
     #[OAT\Response(response: 200, description: 'successful operation')]
     public function endpoint(
+        /* @var string|null $filter An optional filter */
         #[OAT\QueryParameter(description: null)] ?string $filter,
+        /* @var string|null $limit An optional limit */
         #[OAT\QueryParameter] ?int $limit,
     ) {
 

tests/Processors/DocBlockVarLineTest.php

@@ -0,0 +1,54 @@
+<?php declare(strict_types=1);
+
+/**
+ * @license Apache 2.0
+ */
+
+namespace OpenApi\Tests\Processors;
+
+use OpenApi\Processors\Concerns\DocblockTrait;
+use OpenApi\Tests\OpenApiTestCase;
+use PHPUnit\Framework\Attributes\DataProvider;
+
+final class DocBlockVarLineTest extends OpenApiTestCase
+{
+    use DocblockTrait;
+
+    public static function varLineCases(): iterable
+    {
+        yield 'multi-line' => [
+            <<<END
+/**
+ * @example Allan
+ * @var null|string the second name of the customer
+ */
+END,
+            [
+                'type' => 'null|string',
+                'description' => 'the second name of the customer',
+            ],
+        ];
+
+        yield 'split-description' => [
+            <<< END
+/**
+ * The unique identifier of a product in our catalog.
+ *
+ * @var int
+ *
+ * @OA\Property(format="int64", example=1)
+ */
+END,
+            [
+                'type' => 'int',
+                'description' => null,
+            ],
+        ];
+    }
+
+    #[DataProvider('varLineCases')]
+    public function testDocBlockVarLine(string $comment, array $expected): void
+    {
+        $this->assertSame($expected, $this->parseVarLine($comment));
+    }
+}