Re: [boost] CMake and Boost Build tests

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