Question

The thing that really turns me off about Boost is their documentation. What I need is a good reference, and instead of explaining what a good reference is to me I would give example:

java.sun.com/javase/6/docs/api/
Yes I love it. It is also this:
cppreference.com/wiki/stl/vector/start

On the other hand what I find about boost is something like this:
http://www.boost.org/doc/libs/1_40_0/libs/smart_ptr/shared_ptr.htm

Basically some long page of text. Almost no formatting, some bold text here and there and hopefully some links between elements. Not to mention that smart_ptr is one of the better documented libraries.

If you do not find the difference between this and the above examples please stop reading and ignore this post. Do not get me wrong, I write C++ and I use Boost. At my firm we use at least 4 of their libraries, still each and every time I need to check a method prototype for instance it gets me out of my nerves scrolling through their essays. And yes I know that Boost is a collaborative project and that different libraries are developed by different teams.

So does any of you share my disappointment with Boost’s reference and do you know some better site documenting the Boost libraries?

Answer 1

In general, I don’t find the documentation is that bad. In general again, the information is “somewhere” in there. The main problem I see is a lack of uniformity, making it difficult to find that “somewhere”. As you write in your question, the docs were written by different people, and a different times, and that’s probably the cause for this lack of a common structure.

From the java and cppreference links you cite in example, I infer that you are more interested in the synopsis of the interface than in “tutorial” or “motivation” stuff. For shared_ptr, does http://www.boost.org/doc/libs/1_40_0/libs/smart_ptr/shared_ptr.htm#Synopsis provide what you’re after?

For some libs, the “test” and “example” directories under libs/<library_name> are useful.

You may post your questions, comments and suggestions on the boost users and/or documentation mailing lists. From what I see there, specific documentation improvement suggestions are normally welcomed by the library maintainers.