Re: [boost] Improving Documentation

Subject: Re: [boost] Improving Documentation
From: Eric Niebler (eniebler_at_[hidden])
Date: 2013-10-12 13:59:40

On 10/12/2013 9:48 AM, Robert Ramey wrote:
> Mathias Gaunard wrote:
>> You can then reference your concept in Doxygen in the
>> documentation of a function (template or not), or from Quickbook.
> 
> I realize this.  It sounds like you're agreeing with me that 
> Doxygen/Quickbook are not good tools for generating this (essential,
> for me) aspect of the reference documentation.

Right, because doxygen parses comments in C++, and concepts are not
(yet) a standard part of C++. If and when they are, I'm sure doxygen
will support them.

I've also been frustrated by the poor support for concepts in our
documentation toolchain. "Just write your docs in Boostbook XML" is like
telling people to program in assembly -- if assembly were extremely verbose.

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. (Robert, can you
please point me to the editor you use?)

I'll add my voice to those who find the header-first reference layout
less than ideal, although I say that without a concrete suggestion for
improving it.

-- 
Eric Niebler
Boost.org
http://www.boost.org