Re: [boost] Documentation for Boost libraries

From: Christopher Kohlhoff (chris_at_[hidden])
Date: 2008-07-01 08:53:44

Michael Marcin wrote:
> For instance while doing an async_read I passed in a buffer created from 
> the asio::buffer function by passing a std::vector. The reference 
> documentation says:
> 
> "An individual buffer may be created from a builtin array, std::vector 
> or boost::array of POD elements. This helps prevent buffer overruns by 
> automatically determining the size of the buffer: "
> 
> I took this to mean that if I passed in a std::vector it would resize 
> the vector to the size required to complete the read. I found out that I 
> was wrong rather abruptly when I got a crash after passing in an empty 
> std::vector.

Thanks for the report. I have clarified this in the documentation.

> On the whole I probably learned more from the comment blocks above the 
> Asio functions than the documentation.

Hmm, well the documentation is partly generated from the comment blocks, 
so it's serving its purpose either way I guess.

> I really want to learn how to write better and more efficient networking 
> with Asio but the documentation seems to be a reference for people that 
> already know networking well.

Yes, some familiarity with BSD-style sockets is fairly essential for
using Asio's networking support, and I will make this clear in the
documentation for 1.36.

> For instance the design section says:
> 
> "To allow the development of efficient network applications, Boost.Asio 
> includes support for scatter-gather operations"
> 
> But not why or how these make network applications more efficient.

I have to consider this out of scope for the asio documentation, at
least for now. If I included that sort of material it would add hundreds
of pages, and there's already plenty of excellent literature available
(e.g. Stevens).

Cheers,
Chris