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 http://www.boost.org/doc/libs/1_35_0/doc/html/boost_asio/design.html
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