Proper Documentation on http::request and http::response

[xhimanshuz]

In boost Beast documentation nowhere mentioning how to properly create the Request and Response object.
Boost Beast Reference page is missing some basic things, So, I have to watch all your great talk to make me motivated to use Beast even if these are too great and knowledgeable, can't cover all the Beast features. I really like how fast you try to cover the content in a limited time.

As for reference, these are the reference page for the Response, Request class, and file_body class.
https://www.boost.org/doc/libs/1_68_0/libs/beast/doc/html/beast/ref/boost__beast__http__request.html
https://www.boost.org/doc/libs/1_68_0/libs/beast/doc/html/beast/ref/boost__beast__http__response.html
https://www.boost.org/doc/libs/1_68_0/libs/beast/doc/html/beast/ref/boost__beast__http__file_body.html

There should be some example at the end of all references, So People get to know how to use them.
I know it's time-consuming but please cover at least basic concepts So, New people like me at least know how to use basic functionality. I have read example Its great still haven't mentioned how to create request and response object.

[stale]

This issue has been open for a while with no activity, has it been resolved?

[xhimanshuz]

No

[vinniefalco]

What's going on with this? @madmongo1

[stale]

This issue has been open for a while with no activity, has it been resolved?

[xhimanshuz]

No

[madmongo1]

I am trying to think how I can best cover the needed information.
Do you think one example that covers the use of each method would be the right thing, or do you think a little example for each method would be better?

[xhimanshuz]

So People get to know how to use them

@madmongo1 So, I mentioned, If you add an example at the end of the page of reference, It will be easy to learn and use.

[klemens-morgenstern]

A reference is not the place to learn, it's to be used by developers already familiar with the library. You shouldn't use the cppreference as an intro to C++ either. While I get that more examples are always better, the response & request objects are seldolmy used alone, and the doc has multiple examples of how to use them right here under Quick look : https://www.boost.org/doc/libs/1_80_0/libs/beast/doc/html/index.html

People might be thrown off by the reference being on the top of the ToC.

[NateSeymour]

@madmongo1 @ashtum Hey! I see that this issue has been stale for a while. Is there still interest in it? I'd be happy to write documentation on request and response.

[ashtum]

@madmongo1 @ashtum Hey! I see that this issue has been stale for a while. Is there still interest in it? I'd be happy to write documentation on request and response.

Yes, that sounds great. It might be helpful to share a draft of the documentation for initial feedback before investing too much time.

[NateSeymour]

@ashtum Sounds great, will do! Just for my reference, do you have any examples of boostorg documentation that you consider to be particularly well-written?

[ashtum]

The documentation needs to be consistent with the rest of the documentation in Beast.

There are already a few examples for request and response in Message Containers. You may want to expand on this by including examples with other body types. To do so, you will need to edit 02_message.qbk and add the necessary code snippets to http_snippets.cpp.

Alternatively, you can edit the Javadoc for each body type and add a concise example. You can find an example here:

beast/include/boost/beast/websocket/stream.hpp

Lines 649 to 655 in fee9be0

	@par Example
	Disabling compression for a single message.
	@code
	ws.compress(false);
	ws.write(net::buffer(s), ec);
	ws.compress(true);
	@endcode

The key is to keep it concise and clear; otherwise, most users will skip it without reading.

By the way, to build the documentation locally, you can follow the guides available here: https://github.com/boostorg/release-tools/tree/develop/build_docs