Re: [boost] Why is the boost documentation so bad?

Subject: Re: [boost] Why is the boost documentation so bad?
From: Jens Weller (JensWeller_at_[hidden])
Date: 2017-09-08 16:11:00

> Gesendet: Freitag, 08. September 2017 um 04:21 Uhr
> Von: "Florian Lindner via Boost" <boost_at_[hidden]>
> An: boost_at_[hidden]
> Cc: "Florian Lindner" <mailinglists_at_[hidden]>
> Betreff: [boost] Why is the boost documentation so bad?
>
> Hello,
> 
> 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
> documentation.
> 
> Please, don't take this offensive, it's just some feedback I wanted to give a long time.

I guess most people get used to the documentation after a certain learning curve.
Also maybe the software which generates the documentation could be improved to generate better docs.

I often also find Boris Schälings site on boost helpful:
https://theboostcpplibraries.com/boost.pointer_container

This is kind of what is missing in the Documentation for boost.

thanks,

Jens Weller