Re: [boost] Improving Documentation

Subject: Re: [boost] Improving Documentation
From: Mathias Gaunard (mathias.gaunard_at_[hidden])
Date: 2013-10-15 09:47:01

On 14/10/13 19:39, Paul A. Bristow wrote:
>
>
>> -----Original Message-----
>> From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of Mathias Gaunard
>> Sent: Monday, October 14, 2013 10:55 AM
>> To: boost_at_[hidden]
>> Subject: Re: [boost] Improving Documentation
>>
>> 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?

Doxygen is for documenting entities of the C++ language within C++ 
source code.
Concepts are not entities in that language and do not appear in the 
source code, and thus cannot be documented by Doxygen.

I'm not talking about referencing a concept in the documentation of a 
function or class tempalte, that stuff is indeed done with Doxygen and 
causes no problems 
(\xmlonly<conceptname>MyConcept</conceptname>\endxmlonly, that you can 
wrap in a doxygen alias if you prefer to have \conceptref{MyConcept} 
instead)

I'm talking about defining the concept itself in Boostbook, which is an 
XML format.
See for example the various xml files at 
$BOOST_ROOT/libs/proto/doc/reference/concepts/
which generate
<http://www.boost.org/doc/libs/release/doc/html/proto/reference.html#proto.concepts>

Interestingly, as far as I can tell, only Boost.ConceptCheck and 
Boost.Proto use the real Boostbook format for concepts (my own libraries 
not accepted into Boost also do)

Writing those XML files by hand is indeed not great, and we could extend 
Quickbook or use another tool to generate them instead.