Re: [Boost-docs] Query regarding boostbook and documentation

Subject: Re: [Boost-docs] Query regarding boostbook and documentation
From: Robert Ramey (ramey_at_[hidden])
Date: 2016-01-09 20:47:56

On 1/9/16 10:19 AM, Paul A. Bristow wrote:

>> 1) Show how to create concept checking classes be it via boost concept checking and/or concepts
> lite.
>> Users would write these as C++ header files.

I wanted to expand a tiny bit on this point.  I posted an answer to a 
question on Stack Overflow where is describe this

http://stackoverflow.com/questions/10087171/documenting-a-c-concept-using-doxygen/34698653#34698653

Here is the text:

I suggest you consider the following:

a) Look at the documentation for the Boost Concept Checking library. 
This documentation shows you how to make a class which can be used in 
your code to verify that at type actually fulfill the requirements of 
the concept you want to define. You use it like this:

template<typename T>
my_class{
   MyConcept(T); // provokes compile error if T does not match concept
   T m_t;
};
FYI there is a one to one correspondence between the elements used in 
creating the concept checking class and and the concepts lite proposal. 
So when concepts lite is actually working, the transition should be easy.

b) Now use DOxygen to document the MyConcept checking class !!!

c) Use DOxygen /tparam on my_class documentation to refer to MyConcept

c) So now you have exactly what you're asking for!!! - a separate page 
for your concept, and the ability to reference it from all the class 
which require that concept.

The upshot is that I've now come to believe that DOxygen itself doesn't
have to be mucked with much.  The "Concept Page" can be created with
just the facilities of DOxygen itself.  Another way of looking at
this is that a clauses and "shape" of a "Concept Page" is the
same as that of the class that one should build with the Boost
Concept Checking library.  So Documenting a concept and implementing
in terms of BCC now would boil down to the same maintenance
task.

Note also that this is unrelated to DOxygen per se.  In the
creation of the documentation for the Safe Numerics library,
I did exactly the above - but rather than using DOxygen I used
XMLMind.  That is the "trick" is to see that documenting the
concept checking class turns out to be equivalent to documenting
the concept itself - regardless of the tool used to do the job.

I appologize if this seems a little confusing. It took me a
while to see it.

Robert Ramey