Boost logo

Boost :

Subject: Re: [boost] CMake and Boost Build tests
From: Robert Ramey (ramey_at_[hidden])
Date: 2017-07-27 15:30:48

On 7/27/17 3:24 AM, Paul A. Bristow via Boost wrote:

> Works for me.
LOL - of course that makes me feel much better
>> I'm sorry you found them that way, Doxygen I hate
> I also don't like the *look* of its readable output.

Actually, I don't have much complaint about the look. This is
subjective after all. And much / most of the look is in the xslt
transforms which create the html.
> But
> *Doxygen comment syntax for annotating classes, functions, macros etc works OK, and is the nearest thing to a Standard for
> annotating code, and not just C++.*

Right - and that's a problem. In a recent survey, over 90% of users
stated their biggest problem with open source is the documentation or
lack thereof. Composing the two facts above yields the conclusion:

"Standard user documentation of software is found to be unsatisfactory
by over 90% of users"

How can this be anything but bad.

<snip> Doxygen excerpt.

> Doxygen can now use the Clang compiler to extract all this into a form that other programs can then use to lay out in a
> human-readable (or other machine readable form). (Doxygen makes a good stab at template-heavy C++, but isn't a compiler).
> I believe that this is the way forward to producing documentation in the style we prefer (or in the style that others that others
> prefer).
>> (to be fair it's mostly the way folks use it rather than the tool itself),
> +1

This can be said for many tools. And DOxygen is founded on a nobel idea
- literate programming. But it fails to keep up when the problem is
more complex - e.g. Templated programming libraries. And in fact leads
a programmer to think he's explained something when in fact all he has
done has places a good looking facade on a header file.

> but Quickbook works extremely well for me
> + more than 1

In defense of quickbook, it's a reasonable approach to editing XML for
which very few, if any, reasonable alternatives have been proposed. I've
had limited exposure to quickbook. But what I have had does not
encourage me. It does work but when I wanted to add something which
seemed simple, had to go back to the mailing list. Little languages is
an attractive concept. But in practice it turns in to "unfinished"
language. In any case I think a big source of the problem is DOxygen
which gives the programmer a false sense of security that he's solve an
annoyingly tedious problem and can now move on - when in fact he hasn't.

>> As for the toolchain.... I find it amusing
>> that this is the one thing folks most often complain about... even
>> citing it as an example of why we shouldn't invent stuff ourselves...
>> when it's actually the one thing that was *not* invented here!
> It works for me - most of the trouble is with bjam syntax and dealing with MS file naming.

The tool chain is a problem - so I use a 4/5 line shell script. This is
bad enough. But then we have to compound the problem by trying embed the
substance of this script into bjam - a whole other system - just to save
a 5 line script. Now when you need to customization - you have to dive
back into bjam. Sorry this is not an effective usage of one's time.

Robert Ramey

Boost list run by bdawes at, gregod at, cpdaniel at, john at