[Boost-docs] Using automatic doxygen documentation with Boost Concept Check

Subject: [Boost-docs] Using automatic doxygen documentation with Boost Concept Check
From: Mathias Gaunard (mathias.gaunard_at_[hidden])
Date: 2009-07-30 13:07:05

I am running into a few problems with the automatic doxygen 
documentation of my library after adding concept checking to it.

First, the documentation (I don't know which of doxygen or boostbook is 
at fault) seems to fail miserably -- and by that I mean random private 
members being documented as namespace level globals -- if 
BOOST_CONCEPT_REQUIRES is not expanded.
The default expanding is not really nice for a reference documentation, 
so if anyone knows of a definition of BOOST_CONCEPT_REQUIRES that plays 
nice please tell me. For now I'm using "BOOST_CONCEPT_REQUIRES(a, b)=/** 
Requires: a */ b ".

Also, I am defining concepts using the caramel extension to boostbook, 
which has the effect that any type template parameter named with the 
name of a concept is automatically turned into a link to that concept.
Since the new naming policy of the Boost Concept Check Library is to 
name the concept checking class the same name as the concept, this has 
the unfortunate effect that I have to write, for a concept named "Pipe":

template<typename Pipe>
BOOST_CONCEPT_REQUIRES(
     ((boost::Pipe<Pipe>)),
     (special_pipe<Pipe>)
) make_special_pipe(Pipe p)
{
     return special_pipe<Pipe>(p);
}

Not only do I have to disambiguate with boost::, which is quite verbose, 
the documentation appears to be quite confused as Pipe in 
special_pipe<Pipe> will be a link to the concept checking class, which 
is completely wrong.

I personally chose to follow the old naming policy of concept 
(PipeConcept is the name of the concept checking class, not Pipe) to 
solve the issue, but any alternative would be appreciated.