A Better Boost reference?

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%5F40%5F0/libs/smart%5Fptr/shared%5Fptr.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

If you are looking for an introductory text I found the Bjorn Karlsson book very good. It was a while ago when I read it so there may be more up to date texts available now. Find it here.

Answer 2

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.

Answer 3

Looking at the Java link provided, well more than half of it is obsolete for quite some time now :)

You have PDF tools and PDF format of the docs now.. There are tools and more on its way, from boostbook for lib writers ages ago to synopsis and more.. Build your own or parse existing majority of markup cost to an already overblown project :)

Answer 4

I most definitely agree. Javadoc is nasty, nasty stuff. But it is thorough and consistent across nearly every project. Compare the browsability of a random Jakarta project's documentation with that of a random Boost project.