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