Add config for optional use of response return comments as response descriptions

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

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);

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();
+    }
+}