Subject: Re: [boost] Why is the boost documentation so bad?
From: Edward Diener (eldiener_at_[hidden])
Date: 2017-09-08 18:54:09
On 9/7/2017 10:21 PM, Florian Lindner via Boost wrote:
> I really love to use boost libraries in my project, but I always wonder, for such an accomplished project, why is the
> documentation so bad?
> A few examples:
> I want to get familiar with http://www.boost.org/doc/libs/1_65_1/libs/ptr_container/. What do I need to include? Neiter
> the tutorial, the reference or the usage guidelines mention a #include line. This is something which stroke me quite
> often at various boost libs.
> Also with the ptr_container lib, I want to find the refrence for the ptr_vector::insert function. I got to scan the
> reference pages of all members of it's class hierarchy to find the insert() function (it's in ptr_sequence_adapter).
> References and example code often have no syntax highlightning and no linking and it's extremely hard to find
> documentation for a specific symbol, or from there, to jump to the source code.
> I would really like to have a more uniform and a documentation that not feels like a annotated source code dump.
> I use doxygen for my own projects and I know it can generate nicely looking, with syntax highlightning and linked
> Please, don't take this offensive, it's just some feedback I wanted to give a long time.
Feel free to open an issue for any library's documentation you feel
I completely agree with you that every library needs to specify these 3
things near the beginning of the docs:
1) Level of c++ supported if it is anything above c++03.
2) Header files needed
3) Namespaces used
4) Build instructions for non header-only libraries
Furthermore I believe that some Boost documentation suffers from the
syndrome that library authors believe that adequate docs mean
examples/tutorial + reference, without having to provide any general
explanation and discussion of the actual concepts of the library. But
obviously most Boost libraries are first rate in explaining themselves
and it is very hard to change the mindset of those few library authors
who do not want to explain their libraries in a more expansive manner.
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk