From: Edward Diener (eldiener_at_[hidden])
Date: 2008-06-27 18:50:10
David Abrahams wrote:
> Edward Diener wrote:
>> Today, looking for a socket library to use in my C++ code I decided to
>> look at the documentation for ASIO. I was shocked to find out that there
>> is no overview of the functionality of this library at all, but just a
>> series of tutorials and examples and then a reference listing a
>> multitude of classes.
>> I do not believe this is adequate for explaining library functionality
>> and puts a totally unnecessary burden of the end-user when learning the
>> functionality of a library.
> I just looked at the ASIO docs, and I have to agree that exposition of
> basic concepts is needed right from the beginning. However, I think I
> did find much of what I'd want to know to get started with the library;
> it was buried in
These are different notes about various ways functionality has been
designed in the library, which is certainly useful, but they provide no
high order overview of what functionality actually exists in the library
and how the end user should use it.
From the tutorials I would guess that the library, consisting of some
120+ individual items as specified in the reference, has to do with
using network sockets, in synchronous and asynchronous mode, and nothing
else. Perhaps this is true but that is an awful lot of items just for
dealing with socket programming in ASIO. Even here a good general
introduction to socket programming with ASIO would have been welcome. Of
course something tells me that there is more to the library than just
network socket programming, but I do not have the patience to dig into
this by looking at some 120 individual items to see what each one
encompasses. Nor do I have the patience to try to figure out how those
items relate to each other. This is what a good overview should do.
I view this documentation weakness as a real failure of explaining even
the most basic things one wants to know about a library, and for this to
happen in a Boost library seems really poor to me.
This is not meant to be a reflection on the programmer, Christopher
Kohlhoff, nor on the implementation, for what little I can get from an
initial perusal of the documentation the library seems useful. But it is
not the way to write documentation for a Boost library and I am really
surprised that the library was accepted with the documentation in the
form that it has.
It is very important for developers to take a look at documentation from
the end-users point of view, even when the end user is a programmer
himself. Clearly the great majority of Boost libraries do this and
provide the end-user with the necessary introduction/overview to
understand the uses of a library. I do feel that the ASIO library, in
its tutorials, has done this to a very limited degree.
I do understand that the developer's native language may not be English
so that he was much more comfortable explaining the implementation by
tutorials rather than a well organized overview
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk