Documentation for Boost libraries
In general Boost has many libraries with good to absolutely first class documentation. Among the many Boost libraries I have used, all with good documentation, are regex, iostreams, function, bind, optional, signals. tribool, tokenizer, and spirit, but of course there are many other libraries with great documentation in Boost. One of my prerequisites for a library with good documentation is that some sort of overview must be given for the functionality of the library so that the end user knows what is available, and what each available part of the library generally entails. For me this overview must be written out and not just given as a series of programming examples, whether in the form of tutorial code, example code, or whatever one wants to call explanations of functionality based almost purely on some hypothetical program or mini-program. In this I may be different from many programmers but I just find it very hard to understand library functionality from example code without basic generalized explanations of functionality. 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 would like to encourage Boost developers to always give an overview of the functionality of their library and its general concepts and classes, as almost all libraries currently do. While I am appreciative of tutorials and exmaples as an extra learning device, I do not believe that library documentation should exist with some sort of overview, as mentioned above. I have written this because I am disturbed that ASIO was accepted with the sort of documentation which has been created for it. I do not think such a way of presenting a library is adequate for an organization like Boost whose overall excellence is acknowledged throughout the C++ community.
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 HTH, -- Dave Abrahams BoostPro Computing http://www.boostpro.com
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
On Sat, 28 Jun 2008 00:50:10 +0200, Edward Diener <eldiener@tropicsoft.com> wrote:
[...]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
Yes, the name Boost.Asio is misleading for those who look for a network library. If you don't happen to read the description of Boost.Asio at http://www.boost.org/doc/libs/1_35_0 you miss the library. But then the description itself is misleading as it gives developers the impression Boost.Asio is a network library which should have been really called Boost.Net: "Portable networking, including sockets, timers, hostname resolution and socket iostreams." While today nearly all I/O objects in Boost.Asio deal with network functions you can extend Boost.Asio with new I/O objects which don't do networking. But it turned out that this isn't even known in the Asio mailing list. Boost.Asio is really a library to support *any* asynchronous I/O functions which include network functions which again happen to be the only ones supported by Boost.Asio out of the box. If you have a look at http://www.highscore.de/boost/file_monitor.zip though you get an idea how you can create a new I/O object which notifies you asynchronously when a file is changed. Boris
[...]
Boris wrote:
On Sat, 28 Jun 2008 00:50:10 +0200, Edward Diener <eldiener@tropicsoft.com> wrote:
[...]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
Yes, the name Boost.Asio is misleading for those who look for a network library. If you don't happen to read the description of Boost.Asio at http://www.boost.org/doc/libs/1_35_0 you miss the library. But then the description itself is misleading as it gives developers the impression Boost.Asio is a network library which should have been really called Boost.Net: "Portable networking, including sockets, timers, hostname resolution and socket iostreams."
While today nearly all I/O objects in Boost.Asio deal with network functions you can extend Boost.Asio with new I/O objects which don't do networking. But it turned out that this isn't even known in the Asio mailing list. Boost.Asio is really a library to support *any* asynchronous I/O functions which include network functions which again happen to be the only ones supported by Boost.Asio out of the box. If you have a look at http://www.highscore.de/boost/file_monitor.zip though you get an idea how you can create a new I/O object which notifies you asynchronously when a file is changed.
It is very nice that ASIO has all of this functionality which you mention but since the overview documentation, aside from the tutorials and examples, is nonexistent it would take a more persistent programmer than I am to figure out how to do anything with the library other than socket programming. Even in the latter regard I find the lack of an overview to be daunting as I do not learn libraries well from tutorials/examples, but do from actual documentation with conceptual explanations.
Edward Diener wrote:
It is very nice that ASIO has all of this functionality which you mention but since the overview documentation, aside from the tutorials and examples, is nonexistent it would take a more persistent programmer than I am to figure out how to do anything with the library other than socket programming. Even in the latter regard I find the lack of an overview to be daunting as I do not learn libraries well from tutorials/examples, but do from actual documentation with conceptual explanations.
I agree. Last week I had to create a prototype for a real-time multiplayer game including multiple clients and a server. I've been meaning to look at Asio for a while so I used it for this project. I started by reading the using Boost.Asio, tutorial and design sections. After I finished this I really still had almost no idea how to use the library to accomplish my task. I then looked to the examples and found that that chat program was probably the closest thing to what I needed. I found the code for it to be somewhat convoluted and includes no comments at all. I finally found some information I could digest in the reference section. For my demo server io_service run worked fine but I didn't want to deal with the complexities of multithreaded code for the client in my timefram. I eventually found io_server poll which suited my clients needs but I don't recall seeing this outside of the reference. I came to some incorrect conclusions based on the reference material that didn't show up until they were runtime errors. 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. On the whole I probably learned more from the comment blocks above the Asio functions than the documentation. Eventually I did manage to cobble together something that appears to function which is all I needed for my current task and it was easier than using winsock directly which I haven't done in several years. 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. 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. Thanks, Michael Marcin
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
Christopher Kohlhoff wrote:
Michael Marcin wrote:
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).
I agree however if there are ways to use the library that are more efficient than the obvious way I feel some further information should be included in the documentation. For instance a link to a website or a reference to a book that supports and explains the efficiency claim would be sufficient and appreciated in this case. Thanks, Michael Marcin
Edward Diener wrote:
It is very nice that ASIO has all of this functionality which you mention but since the overview documentation, aside from the tutorials and examples, is nonexistent it would take a more persistent programmer than I am to figure out how to do anything with the library other than socket programming. Even in the latter regard I find the lack of an overview to be daunting as I do not learn libraries well from tutorials/examples, but do from actual documentation with conceptual explanations.
Improving the asio docs is an ongoing project. I'm sure that the format is currently biased towards my personal preference when it comes to using documentation. Your grievances are duly noted. I'm already working on a set of use-case based entry points for the documentation, which will serve as an overview, as since 1.35 the library has grown from just networking to serve other needs like serial ports, descriptors, windows handles, etc. I'm planning this for 1.36, but my time is very limited so we'll see how much of it gets in. Cheers, Chris
Hello, As a Boost user, I find indeed very useful to have the same structure in almost every Boost docs, and I'm disturbed when it's not the case. The 2 most useful things in my opinion are a "quick start" or "overview" section at the very beginning as Edward said, and having in each page that presents a new class/function the precise header in which in can be found (very annoying when it's not indicated). Shouldn't Boost define a few elements like those ones that would have to be present in the documentation for a library to be accepted? Bruno
Bruno Lalande wrote:
Hello,
As a Boost user, I find indeed very useful to have the same structure in almost every Boost docs, and I'm disturbed when it's not the case. The 2 most useful things in my opinion are a "quick start" or "overview" section at the very beginning as Edward said, and having in each page that presents a new class/function the precise header in which in can be found (very annoying when it's not indicated). Shouldn't Boost define a few elements like those ones that would have to be present in the documentation for a library to be accepted?
Yes, IMO we should have clearer standards for documentation. There is a whole mailing lists dedicated to Boost documentation issues; maybe you should discuss the details there: http://www.boost.org/community/groups.html#boostdocs -- Dave Abrahams BoostPro Computing http://www.boostpro.com
Yes, IMO we should have clearer standards for documentation. There is a whole mailing lists dedicated to Boost documentation issues; maybe you should discuss the details there: http://www.boost.org/community/groups.html#boostdocs
OK thanks, I just subscribed. For my information, has there already been some discussion on that list about this precise subject? Bruno
Bruno Lalande wrote:
Yes, IMO we should have clearer standards for documentation. There is a whole mailing lists dedicated to Boost documentation issues; maybe you should discuss the details there: http://www.boost.org/community/groups.html#boostdocs
OK thanks, I just subscribed. For my information, has there already been some discussion on that list about this precise subject?
I don't know; we keep list archives so you can answer that sort of question yourself. -- Dave Abrahams BoostPro Computing http://www.boostpro.com
participants (6)
-
Boris -
Bruno Lalande -
Christopher Kohlhoff -
David Abrahams -
Edward Diener -
Michael Marcin