Re: [boost] Asciidoc, an alternative for documentation

Subject: Re: [boost] Asciidoc, an alternative for documentation
From: Robert Ramey (ramey_at_[hidden])
Date: 2017-10-08 02:19:49

On 10/7/17 2:55 PM, Niall Douglas via Boost wrote:

>> a) Our (boost and C++ generally) problem is not rooted in the tools,
>> though the tools don't help much.
> 
> Boost tooling is painful. I have to think with Boost tooling. I don't
> want to have to think, I want to get on with it.

Ahhh, this explains a lot.  Don't do it this way.
> doxygen suffers badly from this too as soon as you push it a bit. You
> end up writing lots of simplifying constructs for it with #ifdef.
> Painful. Standardese doesn't suffer from that part at least.

I'm always down on DOxygen.  But that's a little unfair.  If DOxygen is 
restricted to filling in the reference section it's OK.  It can be made 
work in this role.  The probem comes when one starts to thing that this 
product IS the documentation.  It's only part of - the easy part.  It's 
a paraphrase and formating of the header files.  Of some value granted. 
But I'm afraid that many developers stop there and consider themselves 
done.  Or they try and "extend" DOxygen through macros to handle things 
for which it's not a good fit.

My approach described above is really helpful.  It makes the 
documentation much less tedious to write.  and shorter too.  And it 
makes your code simpler and shorter also.

Try it and get back to me.

Robert Ramey