Re: [Boost-users] Why is there so much co-dependency in Boost? Is there anything to be done about it?

Subject: Re: [Boost-users] Why is there so much co-dependency in Boost? Is there anything to be done about it?
From: Lars Viklund (zao_at_[hidden])
Date: 2012-09-05 03:23:59

On Wed, Sep 05, 2012 at 07:13:05AM +0200, Vicente J. Botet Escriba wrote:
> Le 05/09/12 00:10, Lars Viklund a écrit :
>> There's some Boost libraries that are completely implicit about which
>> headers contains what parts, which makes it some major guesswork to get
>> the bits and pieces you want included, especially if you do not have
>> #include-completion in your editor.
>>
> As for example ...

My statement was what I subjectively felt during hacking sprees when I
know what I want, but can't readily find where it's located when reading
about it in the main body of the documentation.

Going through the libraries, it seems to be mostly a matter of lack of
such detail in the prose non-reference sections, particularly around the
sections that introduce a new concept and for the inline samples, like:
* Bimap tutorial;
* Chrono user's guide;
* Concept;
* Context only has "include all.hpp or the individual headers", with no
  reference listing of headers and types at all;
* Filesystem v3 only documents top-level filesystem.hpp and
  filesystem/fstream.hpp;
* Iterator - the only mention of headers at all is in the top-level
  bullet points for a few of the types;
* Lambda has a brief listing in Installing, but nothing in-line;
* Locale doesn't mention headers by name, but as it's Doxygenish, it
  links most names to the header page where they live.
* MSM doesn't even mention any all-header, it just seems to assume you
  know exactly what headers to use, and the reference section is flat;
* MPL tutorial;
* NumericConversion's only mention of any headers is in examples for
  the sections;
* Parameter has a decent set of cross-referenced docs, once you find it
  under section 7 - until that point no mention of the headers exists;
* PointerContainer lacks header mentions in both the tutorial and the
  reference, with the latter surprising as the reference doesn't contain
  any header information at all, instead having to go to the non-common
  'Library headers' section;
* Polygon seems to be completely lacking any header information
  whatsoever;
* ProgramOptions - no mention in the tutorial, overview or howto;
* PropertyTree - reasonably straightforward based on the names of the
  headers in the reference; prose rarely links typenames to the right
  headers;
* Range separates the reference and the header structure; confusing if
  you've finally gotten used to information being in the reference
  section;
* Test only mentions headers occasionally in samples, I've yet to find
  anything standalone talking about includes at all, except for the
  unrecommended standalone header;
* Thread lacks an overview of the headers, mentioning them occasionally
  in the reference - I just give up and use the all-header;
* Wave has no top-level index, but the few sections mention all headers
  by name and synopsis and links to (disabled in Trac) trunk versions of
  the headers;

The libraries that use qbk-style documentation tends to be pretty
acceptable, as the common style means that you get a list of headers on
the landing page for the library. While not optimal while reading, it's
at least something.

This might not be a major problem if you're willing to manually
cross-reference the reference sections when reading the
tutorial/guide/introduction sections in which is where the meat of the
documentation usually is located, but it feels quite the wrong way
around to dive into header listings to find the type/concept you want,
when the main body of documentation around it is in the prose.

On an unrelated note, the next time I have to use the expandos in the
Iostreams or Serialization documentation, I'm going to cry. They're such
fiddly and tiny targets, so unfriendly that I think more than once about
using the library due to the inaccessibility of the documentation.

Now that I've insulted practically every single Boost author, let me say
"good job, everyone". The level of documentation in Boost is way better
than what you usually see out in the wild, it's just that it's quite
easy to feel disorientated.

-- 
Lars Viklund | zao_at_[hidden]