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