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@acc.umu.se