Boost logo

Boost :

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}

I'm talking about defining the concept itself in Boostbook, which is an
XML format.
See for example the various xml files at
which generate

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.

Boost list run by bdawes at, gregod at, cpdaniel at, john at