C ++ concept documentation using doxygen?

Question

Is there a convenient way to document the C ++ concept in doxygen? I would like to have type documentation in the acceleration documentation .

Answer 1

What you can do is define a custom tag called Concept, which you can use when you describe. an example is to use the alias mechanism in Doxygen, something like:

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

Answer 2

After some problems with Doxygen, I finally came up with the following solution.

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

  • Adding a concept to one (or more) parent concept (s) without changing the parent concept itself (refinement / generalization of concepts)
  • Associating an object with several concepts without changing the concept itself (for example, when adding a class to a library that implements a certain 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, @cf an instance. * * @par Valid Expressions * - @cf function object is ... * - <b>f.result()</b> returns ... * @} */ 

• Define a custom concept command with one argument:

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

  Command:

  • includes the object in the group defining the concept: the object appears in the concept documentation (the object can appear in several groups)
  • adds a paragraph with Implemented concepts , which provides a link to an implemented concept.

• 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 have not found a way to create good documentation, for example in Boost (nice tables for a valid expression, etc.), but at least this documentation organization separates things perfectly.

Answer 3

You can use \tparam to comment / document template options .

Answer 4

I am currently using separate manual pages to document concepts and grouping with \section and \subsection . Then I can associate them with \ref . This works as long as you describe concepts with tables, as in the link you provided, but, unfortunately, do not allow links to individual sections.

I also have an alias to create a list of concepts that are model types.

Answer 5

I suggest you consider the following:

a) See the documentation for the Boost concept validation library. This documentation shows how to create a class that can be used in your code to make sure that the type really matches the requirements of the concept you want to define. You use it as follows:

 template<typename T> my_class{ MyConcept(T); // provokes compile error if T does not match concept T m_t; }; 

FYI is a one-to-one correspondence between the elements used to create the concept validation class and the Lite concept. Therefore, when lite functions actually work, the transition should be easy.

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

c) Use DOxygen / tparam in my_class documentation to reference MyConcept

c) So now you have exactly what you are asking for !!! - A separate page for your concept and the ability to link to it from the entire class that requires this concept.