Re: [boost] Improving Documentation

Subject: Re: [boost] Improving Documentation
From: Mateusz Loskot (mateusz_at_[hidden])
Date: 2013-10-14 19:18:57

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.

> In the C++ reference section this will produce
>
> Template Parameters
>
>     typename T
>
>     The type of the elements stored in the circular_buffer.
>
> T has to be DefaultConstructible
>
> (and circular_buffer and DefaultConstructible will both automatically be hyperlinks - this is what
> Doxygen really does for you).

If it was about hyperlinking stuff, we would have solved it already.

It is about marking, extracting, formatting, synthesizing and interlinking all
of the animals in the C++ vocabulary:

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

hyperlinked to refinements and models as well.

If I havea 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.

Best regards,
-- 
Mateusz  Loskot, http://mateusz.loskot.net