Subject: Re: [boost] Improving Documentation
From: Robert Ramey (ramey_at_[hidden])
Date: 2013-10-12 17:16:46
Eric Niebler wrote:
> 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 use last free personal edition of XMLMind (version 5.1.1).
I describe how I setup for boost documentation here:
and here you can see what the final product looks like for a small library
And while your at it - I'd very much appreciate some feedback on
www.blincubator.com which is my take on how the sand box should work.
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk