[boost] Documentation for Boost libraries

From: Edward Diener (eldiener_at_[hidden])
Date: 2008-06-27 15:11:16

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.