On 12 Oct 2013 at 10:59, Eric Niebler wrote:
For most of my libraries, I'm managed to press Doxygen/Boostbook into service and gotten something I'm mostly satisfied with. Less so for Accumulators, whose documentation is pretty poor, I freely admit. For Proto, doxygen was an abject failure. I used it once to get a crude reference section in Boostbook, then edited it by hand to correct all the flaws, add concept docs, and a complete class and function listing. I've since been maintaining it by hand, and it's awful.
I think you've nailed the documentation problem exactly. Doxygen is pretty good for early 1990s style C++, preferably of the unsurprising boilerplate class variety, where templates are never more complex than cookie cutter template usage such as template<class T> class type_container. When a Boost library gets more metaphysical, then we're pushing the present documentation complexity management systems beyond their capabilities. I think something based on usefully annotating clang's AST is probably the only long term way forward. God knows how to usefully document non-compiler concepts though, I personally find their current documentation presentation confusing because they split up (in my head) prototype from implementation. I'm hoping direct compiler support of concepts will help a lot. Niall -- Currently unemployed and looking for work. Work Portfolio: http://careers.stackoverflow.com/nialldouglas/