Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

doc: How to properly return different kinds of responses? #1375

Closed
cykerway opened this issue Oct 28, 2018 · 3 comments · Fixed by #1529
Closed

doc: How to properly return different kinds of responses? #1375

cykerway opened this issue Oct 28, 2018 · 3 comments · Fixed by #1529
Assignees
@nZac
Labels
documentation

Comments

@cykerway
Copy link

The Response object has several fields that application authors can fill:

media, data, body, stream, context

While I understand they are designed for different types of responses, it's not obvious from documentation how they conflict with one another and which has priority. I think the doc better adds some examples show different kinds of usage.
@anekix
Copy link

anekix commented Oct 29, 2018

@cykerway . isn't it clear from the docs here? https://falcon.readthedocs.io/en/stable/api/request_and_response.html#response.
I can see all fields are very clearly defined.

@cykerway
Copy link
Author

cykerway commented Oct 29, 2018 •
edited
Loading

@cykerway . isn't it clear from the docs here? https://falcon.readthedocs.io/en/stable/api/request_and_response.html#response.
I can see all fields are very clearly defined.

I can see the fields are defined, but the doc doesn't say how they conflict with one another and which has priority. The doc should mention which fields are mutually exclusive so you know you shouldn't set one field if another is set. Furthermore, it's not very clear what context is and how to use it. I did a bit of search but couldn't find a satisfying example.

@vytas7
Copy link
Member

vytas7 commented Dec 28, 2018

Thanks for this very valid suggestion @cykerway !

On a related note, we have also created an umbrella issue to stress the fact that we are striving after better docs: #1393

@vytas7 vytas7 added documentation needs contributor Comment on this issue if you'd like to volunteer to work on this. Thanks! labels Dec 28, 2018
@nZac nZac self-assigned this May 6, 2019
@nZac nZac added in progress and removed needs contributor Comment on this issue if you'd like to volunteer to work on this. Thanks! labels May 6, 2019
nZac pushed a commit to nZac/falcon that referenced this issue May 6, 2019
docs(response): Add an FAQ entry for response attributes
01f055f 
Fixes falconryGH-1375
@nZac nZac mentioned this issue May 6, 2019
Merged
vytas7 pushed a commit that referenced this issue May 8, 2019
@vytas7
docs(response): Add an FAQ entry for response attributes (#1529)
71bb7b2 
* docs(response): add an FAQ entry for response attributes

Fixes GH-1375

* Fix body / data mismatch
@vytas7 vytas7 removed the in progress label Jul 4, 2020
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@nZac nZac

Labels
documentation
Projects
None yet
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

docs(response): Add an FAQ entry for response attributes nZac/falcon
4 participants
@nZac @cykerway @vytas7 @anekix