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
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.
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk