Documenting a C++ concept using doxygen? [closed]

Question

Is there a convenient way to document a C++ concept in doxygen? I would like to have some kind of documentation like this in the boost documentation.

Answer 1

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.

Answer 2

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\" "

Answer 3

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

Answer 4

I currently use separate manual pages to document concepts and group the with \section and \subsection. I can then link to them with \ref. This works as long as you describe concepts with tables as in the link you gave, but unfortunately will not enable links to single sections.

I also have an alias to create a list of concepts that a type models.