Subject: Re: [boost] Improving Documentation
From: Niall Douglas (s_sourceforge_at_[hidden])
Date: 2013-10-12 19:12:55
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.
-- Currently unemployed and looking for work. Work Portfolio: http://careers.stackoverflow.com/nialldouglas/
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk