Re: [boost] Improving Documentation

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
DefaultConstructible.
> ----------------------------------------------------------------------------------
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> 
> 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
this?
> 
> http://www.boost.org/doc/libs/1_54_0/libs/utility/CopyConstructible.html

If you wish I could tackle this now - but I'm too busy with a bout of industrial strength DIY at
present ;-)

But when I'm free, is this worth tackling?

> If I have a model well_documented, how...like this?
> 
http://www.boost.org/doc/libs/1_54_0/libs/fusion/doc/html/fusion/container/vector.html
> 
> 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
meta-language-ish beast.

Another test-case example?

Cheers.

Paul

---
Paul A. Bristow,
Prizet Farmhouse, Kendal LA8 8AB  UK
[phone]  07714330204
pbristow_at_[hidden]