Skip to content

Add config for optional use of response return comments as response descriptions - #1254

Open
yugarinn wants to merge 3 commits into
dedoc:mainfrom
yugarinn:feature/add-config-for-optional-return-comments
Open

Add config for optional use of response return comments as response descriptions#1254
yugarinn wants to merge 3 commits into
dedoc:mainfrom
yugarinn:feature/add-config-for-optional-return-comments

Conversation

@yugarinn

Copy link
Copy Markdown

Hello there! First of all, thank you for maintaining this package :)

I am opening this PR to cover for a case that bit me this morning. I needed to temporarily comment out a line to push a hotfix into production, and our pipeline kept regenerating the API docs with the comment:

This was the (bad, I know) hotfix:

        $result->update(['updated_at' => now()]);
        // TODO: The platform squad is working on a fix to add PK columns to
        // the `users_devices` table. Until then we cannot do this update since
        // it would result in a full table update (which is bad).
        // 
        // $result->update(['updated_at' => now()]);

        return new UserDeviceResource($result);

And this is what ended up being generated in our API documentation:

-                        "description": "`UserDeviceResource`",
+                        "description": "TODO: The platform squad is working on a fix to add PK columns to\nthe `users_devices` table. Until then we cannot do this update since\nit would result in a full table update (which is bad).\n\n$result->update(['updated_at' => now()]);\n\n`UserDeviceResource`",
                        "content": {
                            "application/json": {
                                "schema": {

I ended up moving the commet way above to avoid this, but it would have been great to have the option to ignore it entirely... thus this PR.

Please let me know if this approach seems correct to you, whether or not it is properly tested, or even if you want this at all! This could also be generalized to enable/disable other features. Another approach could be just ignoring comments that are separated from the return statement by a newline, but I digress.

@yugarinn yugarinn changed the title Add config for optional use of response return comments as response descriptions. Add config for optional use of response return comments as response descriptions Aug 20, 2026
@romalytvynenko

Copy link
Copy Markdown
Member

@yugarinn Thanks for the PR.

I will consider making this a default behavior and parse only status and body annotation. I just need to think a bit on it before merging the PR.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants