On 14/10/13 19:39, Paul A. Bristow wrote:
-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Mathias Gaunard Sent: Monday, October 14, 2013 10:55 AM To: boost@lists.boost.org 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.co... 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.