On Mon, 3 Dec 2018 at 16:58, Vinnie Falco via Boost-users wrote:

It is true that there is a notable lack of authoritative tutorials and guides on all of the finer aspects of using Boost.Asio (and by extension, stand-alone Asio and Networking TS). I don't think it is fair to expect that the author of Asio (Christopher Kohlhoff) should be responsible for writing these things.

I would not expect Christopher to be responsible for writing these things. But you have already written it, if you would offer the patch to add that documentation to Asio wouldn't Christopher take it? It's likely it would reach a wider audience if it were in Asio instead of in Beast. There must be people interested in Asio but not in HTTP/Websocket who may not have bothered to look into the Beast docs.

...

- beast::test::stream (to be fair, it's in experimental)

Interfaces in _experimental/ are very likely to change which is why they are specially marked. They can also have bugs or lack documentation. As these things become fully baked they will be promoted to public interfaces (moved from _experimental to one of the public interface directories).

Sure, but wouldn't make sense for it to be in Asio's experimental instead of in Beast's experimental? It would have a wider audience, which would give you more feedback.

...

But now we even have code to work around issues in Boost.Asio which ideally would simply be fixed in Boost.Asio. For example: beast::ssl_stream.

asio::ssl::stream implementation does not handle scatter/gather I/O. When you call write() with a buffer sequences having length greater than one, it results in a separate I/O for each element of the sequence. This kills performance, especially in Beast where the implementation makes heavy use of buffers_cat. Beast's ssl_stream class is a wrapper which intelligently flattens these sequences at the expense of allocating memory.

I think there's an OpenSSL interface for handling a vector of buffers, so if it was fixed in Asio it would be better as there would be no need to allocate memory. I don't know enough to attempt a fix but maybe there is someone else who could?

Fair enough. Better to have a workaround than nothing. But until somebody with more OpenSSL knowledge comes with a proper fix, wouldn't the workaround be better in the Asio repository? To be fair, I don't know how the different Boost libraries are developed. Maybe it's too difficult for the developer of one library to contribute to another library?

-----Original Message----- From: Boost-users [mailto:boost-users-bounces@lists.boost.org] On Behalf Of Vinnie Falco via Boost-users Sent: 03 December 2018 19:00 To: boost-users@lists.boost.org; Cristian Morales Vega Cc: Vinnie Falco Subject: Re: [Boost-users] Boost.Beast vs Boost.Asio

On Mon, Dec 3, 2018 at 10:25 AM Cristian Morales Vega wrote:

...

But you have already written it, if you would offer the patch to add that documentation to Asio wouldn't Christopher take it?

Well there are a few problems there. He couldn't add it to Boost.Asio without also adding it to stand-alone Asio. My documentation is kind of boost-specific (I'm working on that though). And he would probably have written it differently (or not at all). This means that whenever I want to update it, he will have to also spend time on it. This puts an unnecessary burden on someone. Furthermore it isn't clear that Chris is the best person to be writing tutorials (or myself for that matter). Everyone is specialized differently so I think it is better for the people who have 1. the incentive, and 2. the ability to maintain the work.

Authors should never write their own docs ;-)

...

Fair enough. Better to have a workaround than nothing. But until somebody with more OpenSSL knowledge comes with a proper fix, wouldn't the workaround be better in the Asio repository?

Yes this would be better if it was fixed upstream (in Asio).

...

To be fair, I don't know how the different Boost libraries are developed. Maybe it's too difficult for the developer of one library to contribute to another library?

Each Boost library is like its own kingdom with its own ruler. Within a library, the author is mostly free to do as they wish. It would be nice to resolve some of these issues though.

Do 'see also' links of the form https://www.boost.org/doc/libs/release/doc/html/other_library/... help here help in resolving this? Both libraries could (should even) helpfully cross-link each other? A PR that is just a link is much more likely to be accepted than something that needs real effort? Paul --- Paul A. Bristow Prizet Farmhouse Kendal UK LA8 8AB +44 (0) 1539 561830

On 12/4/18 5:47 AM, Vinnie Falco via Boost-users wrote:

On Tue, Dec 4, 2018 at 2:50 AM Paul A. Bristow via Boost-users wrote:

...

Do 'see also' links of the form

https://www.boost.org/doc/libs/release/doc/html/other_library/... help here

help in resolving this?

Both libraries could (should even) helpfully cross-link each other?

Beast documentation has extensive cross-links to Boost.Asio docs, for example click on return type ("DEDUCED") of these function signatures:

https://www.boost.org/doc/libs/1_68_0/libs/beast/doc/html/beast/ref/boost__b...

...

A PR that is just a link is much more likely to be accepted than something that needs real effort?

I don't know that it makes sense for asio to link back to beast. And that wouldn't be meaningful for the stand-alone version (which shares the same docs).

I think that would be mistake you'd regret for the rest of your life. Cross-linking (in both directions) would effectively make beast/asio one giant library. I know you're talking about only the docs. But if you feel you need to do it for the docs, you've likely intertwined the concepts which determine the design and scope of each library. Bad idea.

Regards

On Tue, Dec 4, 2018 at 6:25 AM Paul A. Bristow via Boost-users wrote:

It is usually best to link to https://www.boost.org/doc/libs/release/libs/beast ... rather than...

I link to a particular version so that the link never goes stale. Who knows, maybe some day networking will be part of the standard library and Beast will use that instead, because Boost.Asio no longer exists? Your link would be stale then, but the version 1.68 will live on in perpetuity. Regards

On 5/12/2018 03:20, Robert Ramey wrote:

I'm aware that this suggestion is made in jest.  But I think it reflects the view of many authors that documentation is a chore that can separated from the library development and design which can most expediently left for last, delegated to doxygen or just skipped entirely. I think this view totally wrong.  It's a sure sign that the one's library is messed up when documenting how to use it and how it works is too difficult to do.  If one is crafting the documents and the code together, difficulties in keeping the documentation working can motivate improvements in the design which make things much simpler. We've had boost submissions where the document is a mess - and generally that implies that the code is also.

+1 Authors must write the first version of the docs, because they're the only ones who know the library well enough to do so. They should remain responsible for the "official" docs thereafter, but incorporate constructive feedback from others on review and trying to actually use them. Things are usually less obvious than the author assumes. :) And design and layout of the documentation is just as important (if not more important) than the design of the code itself. No matter how finely-crafted the code is, a library is useless if nobody knows how to actually use it, or their first instinct is to use it "wrong".