Subject: Re: [boost] Improving Documentation
From: Paul A. Bristow (pbristow_at_[hidden])
Date: 2013-10-15 04:33:19
> -----Original Message-----
> From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of Mateusz Loskot
> Sent: Tuesday, October 15, 2013 12:19 AM
> To: boost_at_[hidden]
> Subject: Re: [boost] Improving Documentation
> On 14 October 2013 18:39, Paul A. Bristow <pbristow_at_[hidden]> wrote:
> >> From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of
> >> Mathias Gaunard On 12/10/13 19:59, Eric Niebler wrote:
> >> > 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.
> >> Maybe Quickbook could be extended to be able to output the required XML for concepts?
> > What is required that is not already provided by Doxygen comments of
> > type
> > \tparam \param \pre \post \returns etc?
> > If we have a concept like
> > template <class T>
> > struct DefaultConstructable;
> > It will be possible to get a link to this from \tparam description
> > \tparam The type of the elements stored in the circular_buffer. T has to be
> This sentence should not even appear there, but something like:
> \tparam The type of the elements stored in the circular_buffer.
> \modelof DefaultConstructible
> and that's important point of the whole debate, IMHO.
OK - modelof would be nice but:
1 We could get \modelof added to Doxygen.
2 The key information DefaultConstructible is present - a big improvement on the current situation.
And if you go to the source hpp, you will also find the comment with this info.
> It is about marking, extracting, formatting, synthesizing and interlinking all of the animals in
the C++ vocabulary:
I have a long term vision of starting with Clang and adding the documenting-from-comments features,
but we are way off that. A GSoC project?
We also perhaps don't want to put a lot of work into making BOOST_CONCEPTS work automatically, only
to find that it obsolete if concepts are added to C++.
For a year or several, we should be using the tools we have to best.
> If I have a concept EasilyDocumentable, how shall I stuff Doxygen with data to get page like
If you wish I could tackle this now - but I'm too busy with a bout of industrial strength DIY at
But when I'm free, is this worth tackling?
> If I have a model well_documented, how...like this?
> with "model of" list of corresponding concepts, valid expressions and semantics would be nice too.
It's OK - but it's very much reference info - it doesn't have hyperlinks to explain much - not even
links to the source files!
As an test example, it's also a bit of a googly because Fusion a bit of a weird and wonderful
Another test-case example?
--- Paul A. Bristow, Prizet Farmhouse, Kendal LA8 8AB UK +44 1539 561830 07714330204 pbristow_at_[hidden]
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk