Re: [boost] Improving Documentation

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).

http://www.blincubator.com/downloads/xxe-perso-5_1_1-setup.exe

I describe how I setup for boost documentation here:

http://rrsd.com/blincubator.com/tools_documentation/

and here you can see what the final product looks like for a small library

http://htmlpreview.github.io/?https://raw.github.com/robertramey/safe_numerics/master/safe_numerics/doc/html/index.html

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.

Robert Ramey