From 126db7b2317e2df1a120d798bd8b50342f295270 Mon Sep 17 00:00:00 2001 From: DerManoMann Date: Wed, 22 Apr 2026 10:05:54 +1200 Subject: [PATCH 1/4] . (cherry picked from commit 77526e00cb6f926f6774057bf745b4c7af078c8c) --- src/Processors/AugmentParameters.php | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/Processors/AugmentParameters.php b/src/Processors/AugmentParameters.php index 3f3eff5a6..6bf7a740c 100644 --- a/src/Processors/AugmentParameters.php +++ b/src/Processors/AugmentParameters.php @@ -136,12 +136,12 @@ 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]; + if (array_key_exists($parameter->name, $operationDocblockParams)) { + $details = $operationDocblockParams[$parameter->name]; if ($details['description']) { $parameter->description = $details['description']; } From b05d4633bd552756c8f6f48598dc4660a172d7e2 Mon Sep 17 00:00:00 2001 From: DerManoMann Date: Wed, 22 Apr 2026 10:06:02 +1200 Subject: [PATCH 2/4] Set parameter comment on context if available (cherry picked from commit d57bedb0bedd9dec699582039dfdb1a73f1bbc0d) --- src/Analysers/AttributeAnnotationFactory.php | 4 ++++ tests/Fixtures/PHP/DocblockAndTypehintTypes.php | 1 + tests/Fixtures/Scratch/PromotedProperty.php | 2 +- 3 files changed, 6 insertions(+), 1 deletion(-) diff --git a/src/Analysers/AttributeAnnotationFactory.php b/src/Analysers/AttributeAnnotationFactory.php index cc5e5cb8c..8312ba059 100644 --- a/src/Analysers/AttributeAnnotationFactory.php +++ b/src/Analysers/AttributeAnnotationFactory.php @@ -94,6 +94,10 @@ public function build(\Reflector $reflector, Context $context): array } } else { $instance->_context->property = $rp->getName(); + if (method_exists($rp, 'getDocComment')) { + $comment = $rp->getDocComment(); + $instance->_context->comment = false !== $comment ? $comment : null; + } } } $annotations[] = $instance; diff --git a/tests/Fixtures/PHP/DocblockAndTypehintTypes.php b/tests/Fixtures/PHP/DocblockAndTypehintTypes.php index dd3c8a81e..68c35b0ef 100644 --- a/tests/Fixtures/PHP/DocblockAndTypehintTypes.php +++ b/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'))] diff --git a/tests/Fixtures/Scratch/PromotedProperty.php b/tests/Fixtures/Scratch/PromotedProperty.php index 95604c546..12d8233f0 100644 --- a/tests/Fixtures/Scratch/PromotedProperty.php +++ b/tests/Fixtures/Scratch/PromotedProperty.php @@ -59,7 +59,7 @@ public function __construct( */ public string $different = '', - /* + /** * Intentionally not promoted! */ #[OAT\Property()] From f2798887f62fa97c58cce97f3664094c3b90ae0f Mon Sep 17 00:00:00 2001 From: DerManoMann Date: Wed, 22 Apr 2026 11:44:05 +1200 Subject: [PATCH 3/4] . (cherry picked from commit 135e3594c846ffdadf827512ddb5f5aaf4e495bc) --- src/Analysers/AttributeAnnotationFactory.php | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/src/Analysers/AttributeAnnotationFactory.php b/src/Analysers/AttributeAnnotationFactory.php index 8312ba059..2557f179a 100644 --- a/src/Analysers/AttributeAnnotationFactory.php +++ b/src/Analysers/AttributeAnnotationFactory.php @@ -94,12 +94,15 @@ public function build(\Reflector $reflector, Context $context): array } } else { $instance->_context->property = $rp->getName(); - if (method_exists($rp, 'getDocComment')) { - $comment = $rp->getDocComment(); - $instance->_context->comment = false !== $comment ? $comment : null; + } + } elseif ($instance instanceof OAT\Parameter) { + if (method_exists($rp, 'getDocComment')) { + if ($comment = $rp->getDocComment()) { + $instance->_context->comment = $comment; } } } + $annotations[] = $instance; } } From e52f543051ecbcac95d02206c4fce907cbd85639 Mon Sep 17 00:00:00 2001 From: DerManoMann Date: Wed, 22 Apr 2026 14:01:28 +1200 Subject: [PATCH 4/4] BACKPORT-CONFLICT --- src/Processors/AugmentParameters.php | 7 +++ src/Processors/Concerns/DocblockTrait.php | 6 ++- tests/Fixtures/Scratch/Docblocks.php | 2 + tests/Fixtures/Scratch/PromotedProperty.php | 2 +- tests/Processors/DocBlockVarLineTest.php | 54 +++++++++++++++++++++ 5 files changed, 69 insertions(+), 2 deletions(-) create mode 100644 tests/Processors/DocBlockVarLineTest.php diff --git a/src/Processors/AugmentParameters.php b/src/Processors/AugmentParameters.php index 6bf7a740c..e609cb390 100644 --- a/src/Processors/AugmentParameters.php +++ b/src/Processors/AugmentParameters.php @@ -139,6 +139,13 @@ protected function augmentOperationParameters(Analysis $analysis): void $operationDocblockParams = $tags['param'] ?? []; foreach ($operation->parameters as $parameter) { + if (Generator::isDefault($parameter->description)) { + $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]; diff --git a/src/Processors/Concerns/DocblockTrait.php b/src/Processors/Concerns/DocblockTrait.php index c72db24ac..22369041a 100644 --- a/src/Processors/Concerns/DocblockTrait.php +++ b/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+(?[^\s]+)([ \t])?(?.+)?+$/im', $comment, $matches); +======= + preg_match('/@var[ \t]+(?[^\s]+)(?:[ \t]+\$(?\w+))?(?:[ \t]+(?.+))?$/im', (string) $comment, $matches); +>>>>>>> 4b1ec56 (Prepare for parameter (`@var`) docblocks) $result = array_merge( ['type' => null, 'description' => null], diff --git a/tests/Fixtures/Scratch/Docblocks.php b/tests/Fixtures/Scratch/Docblocks.php index 8d979566f..16a44d721 100644 --- a/tests/Fixtures/Scratch/Docblocks.php +++ b/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, ) { diff --git a/tests/Fixtures/Scratch/PromotedProperty.php b/tests/Fixtures/Scratch/PromotedProperty.php index 12d8233f0..95604c546 100644 --- a/tests/Fixtures/Scratch/PromotedProperty.php +++ b/tests/Fixtures/Scratch/PromotedProperty.php @@ -59,7 +59,7 @@ public function __construct( */ public string $different = '', - /** + /* * Intentionally not promoted! */ #[OAT\Property()] diff --git a/tests/Processors/DocBlockVarLineTest.php b/tests/Processors/DocBlockVarLineTest.php new file mode 100644 index 000000000..a8f28e40f --- /dev/null +++ b/tests/Processors/DocBlockVarLineTest.php @@ -0,0 +1,54 @@ + [ + << '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)); + } +}