Documenting a C++ concept using doxygen?

After some struggling with Doxygen, I finally came to the following solution.

1. Define a group for your concept: using pages is not that appropriate since a page should indicate its subpages (from top to bottom of the tree), while groups indicate potentially many parents groups. This allows:

   • Adding a concept to one (or more) parent concept(s), without changing the parent concept itself (refinement/generalization of concepts)
   • Linking an entity to several concepts, without changing the concept itself (eg. when adding a class to the library implementing a specific concept)

   Example

   /*!@defgroup measurement_functor_concepts Measurement function objects
    * @ingroup generalconcepts
    * @{
    * @par Description
    * blablabla
    *
    * @par Notations
    * Let @c F be the type of the function object, @c f an instance.
    *
    * @par Valid Expressions
    * - @c f function object is ...
    * - <b>f.result()</b> returns ...
    * @}
    */
   

2. Define a custom command concept with one argument:

   ALIASES += concept{1}="@ingroup \1\n@par Implemented concepts:\n@ref \1"
   

   The command:

   • includes the entity into the group defining the concept: the entity will appear in the documentation of the concept (the entity may appear in several groups)
   • adds a paragraph with Implemented concepts providing a link to the implemented concept.

3. Indicate that a particular class/struct implements the concept:

   //!@brief Does things...
   //!@concept{measurement_functor_concepts}
   template <class T>
   struct my_struct: public std::unary_function<T, void> {};
   

I did not find a way to generate a nice documentation like in Boost (nice tables for the valid expression, etc), but at least this organization of the documentation separates things properly.

What you can do is define a custom tag called Concept, which you can then use as you describe. An example of this is to use the alias mechanism in Doxygen, something like:

ALIASES += "con=\xrefitem con \"Concept\" \"Concepts\" "

You can use \tparam to comment/document on template parameters.