From 43e8a5581ba23b2e16e2ccac64b1572ebbae999d Mon Sep 17 00:00:00 2001
From: yugarinn <yugarinn@proton.me>
Date: Thu, 20 Aug 2026 18:59:40 +0200
Subject: [PATCH 1/3] Add new test case for return response comments

---
 .../ResponseExtensionTest.php                 | 35 +++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/tests/Support/OperationExtensions/ResponseExtensionTest.php b/tests/Support/OperationExtensions/ResponseExtensionTest.php
index 6c9d49e7..85d9952d 100644
--- a/tests/Support/OperationExtensions/ResponseExtensionTest.php
+++ b/tests/Support/OperationExtensions/ResponseExtensionTest.php
@@ -119,3 +119,38 @@ public function toArray(\Illuminate\Http\Request $request)
         return ['id' => 42];
     }
 }
+
+it('allows adding a comment right above the return statement to be used as the response description', function () {
+    $openApiDocument = generateForRoute(fn () => Route::get('api/test', ReturnCommentController_ResponseTest::class));
+
+    expect($responses = $openApiDocument['paths']['/test']['get']['responses'])
+        ->toHaveCount(1)
+        ->and($responses[200]['description'])
+        ->toBe('This description comes from a comment');
+});
+class ReturnCommentController_ResponseTest
+{
+    public function __invoke()
+    {
+        // This description comes from a comment
+        return something_unknown();
+    }
+}
+
+it('allows ignores a comment right above the return statement to be used as the response description if is disabled in configuration', function () {
+    config()->set('scramble.ignore_response_return_comments', true);
+    $openApiDocument = generateForRoute(fn () => Route::get('api/test', ReturnCommentWithOptionDisabledController_ResponseTest::class));
+
+    expect($responses = $openApiDocument['paths']['/test']['get']['responses'])
+        ->toHaveCount(1)
+        ->and($responses[200]['description'])
+        ->toBe('');
+});
+class ReturnCommentWithOptionDisabledController_ResponseTest
+{
+    public function __invoke()
+    {
+        // This description comes from a comment
+        return something_unknown();
+    }
+}

From 02e3b32471abe053f1ebf22f1b5c3f9ff3690fe4 Mon Sep 17 00:00:00 2001
From: yugarinn <yugarinn@proton.me>
Date: Thu, 20 Aug 2026 19:00:12 +0200
Subject: [PATCH 2/3] Add new condition in docType if to take the ignore config
 into account

---
 src/Support/Generator/TypeTransformer.php | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/src/Support/Generator/TypeTransformer.php b/src/Support/Generator/TypeTransformer.php
index 90761d06..1d7a68e0 100644
--- a/src/Support/Generator/TypeTransformer.php
+++ b/src/Support/Generator/TypeTransformer.php
@@ -495,12 +495,15 @@ public function toResponse(Type $type): Response|Reference|null
                 );
         }
 
-        if ($docNode = $type->getAttribute('docNode')) {
+        $returnCommentsShouldBeIgnored = config('scramble.ignore_response_return_comments', false);
+
+        if (!$returnCommentsShouldBeIgnored && ($docNode = $type->getAttribute('docNode'))) {
             /** @var PhpDocNode $docNode */
             $description = (string) Str::of($docNode->getAttribute('summary') ?: '') // @phpstan-ignore argument.type
                 ->append("\n\n".($docNode->getAttribute('description') ?: '')) // @phpstan-ignore binaryOp.invalid
                 ->append("\n\n".$response->description)
                 ->trim();
+
             $response->description($description);
 
             $code = (int) (array_values($docNode->getTagsByName('@status'))[0]->value->value ?? $response->code ?? 200);

From 711b2b71ce0cc97f68dd44344725032705a98336 Mon Sep 17 00:00:00 2001
From: yugarinn <yugarinn@proton.me>
Date: Thu, 20 Aug 2026 19:03:38 +0200
Subject: [PATCH 3/3] Add new ignore option to default config file

---
 config/scramble.php | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/config/scramble.php b/config/scramble.php
index 9001932c..dd2cee73 100644
--- a/config/scramble.php
+++ b/config/scramble.php
@@ -124,6 +124,15 @@
      */
     'enum_cases_names_strategy' => false,
 
+    /**
+     * Determines whether or not Scramble will use comments above
+     * returns in responses to be used as the response description.
+     * Available options:
+     * - true - Comments will be ignored.
+     * - false - Comments will be used (default).
+     */
+    'ignore_response_return_comments' => false,
+
     /**
      * When Scramble encounters deep objects in query parameters, it flattens the parameters so the generated
      * OpenAPI document correctly describes the API. Flattening deep query parameters is relevant until