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.

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

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

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

@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
vytas7 pushed a commit that referenced this issue May 8, 2019
* 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
Projects
None yet
Development

Successfully merging a pull request may close this issue.

4 participants