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.
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk