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

Subject: Re: [boost] Why is the boost documentation so bad?
From: Richard Hodges (hodges.r_at_[hidden])
Date: 2017-09-08 11:25:57

> but I got to grep the source code to find out I need to include #include
<boost/ptr_container/ptr_inserter.hpp> to get the back_inserter.
Documentation was not helpful there.

Well, boost is free software, maintained by a dedicated and much
under-celebrated community of heroes.

In my view it has single-handedly rescued c++ from oblivion and is the
breeding ground for all ideas that eventually go into the standard as
language improvements.

If the documentation is not helpful, it is up to us, the grateful users of
boost, to offer an improvement by submitting a commit, or at least a bug
report to a maintainer.

Otherwise we're just being leaches.

For me, I could not have completed my many programs without:

boost.log,
boost.asio,
boost.algorithm,
boost.msm,
boost.variant,
boost.shared_ptr (before it was in c++),
boost.serialization,
boost.thread (ditto),
boost.regex (ditto),

It's also the only 3rd party library I have used which has given me no
problems (apart from that one time when clang and apple clan diverged over
the keyword thread_local) - even that was fixed in the next release.

The existence of boost has literally saved me writing, testing and fixing
hundreds of thousands of lines of code.

>From me, thank you to everyone who has contributed to boost. You are the
internet's finest.

On 8 September 2017 at 04:27, Florian Lindner via Boost <
boost_at_[hidden]> wrote:

> Another example which just occured to me:
>
> http://www.boost.org/doc/libs/1_65_1/libs/ptr_container/doc/
> ptr_inserter.html tells me how to copy elements, but I got
> to grep the source code to find out I need to include #include
> <boost/ptr_container/ptr_inserter.hpp> to get the
> back_inserter. Documentation was not helpful there.
>
>
> Am 08.09.2017 um 10:21 schrieb Florian Lindner:
> > 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.
> >
> > Best,
> > Florian
> >
>
> _______________________________________________
> Unsubscribe & other changes: http://lists.boost.org/
> mailman/listinfo.cgi/boost
>