Re: [boost] Improving Documentation

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.

Niall

-- 
Currently unemployed and looking for work.
Work Portfolio: http://careers.stackoverflow.com/nialldouglas/