Documenting a C++ concept using doxygen?

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.

score 7 · Answer 1 · answered Mar 19 '13 at 15:21

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

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 ...
 * @}
 */
```
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.

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.

score 3 · Accepted Answer · edited Mar 26 '19 at 10:03

3

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

edited Mar 26 '19 at 10:03

albert

8,285
3
19
32

answered Apr 10 '12 at 13:31

JadziaMD

2,690
5
31
42

3

I'm sorry, but it's not obvious how defining an alias helps in documenting concepts. Can you expand on this answer, perhaps with an example? – Emile Cormier Mar 13 '15 at 16:34

score 2 · Answer 3 · edited Dec 22 '18 at 11:51

2

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

edited Dec 22 '18 at 11:51

albert

8,285
3
19
32

answered Apr 10 '12 at 10:43

Attila

28,265
3
46
55

1

I could use '\tparam' to say that the class instantiating this template parameter should be implemented in terms of concept xyz. But how document the concept itself? – proto Apr 10 '12 at 11:46
Not sure I understand what you are looking for. You can make a `\note` saying that xyz concept is so-and-so, but that's probably not the best place to write the documentation for the concept itself. If you have an actual class/struct for the concept, you can write the documentation for it as you would for any other class – Attila Apr 10 '12 at 12:18
1

Since there is no way to specify a concept using C++ (as of yet) there is no class (or file) describing the concept. There are only classes implementing it. I wondered if there is an established way to circumvent this and include documentation for concepts in my doxygen output. – proto Apr 10 '12 at 12:50
You could take a look at [this SO thread](http://stackoverflow.com/questions/3435225/c-meta-programming-doxygen-documentation). Also note [grouping](http://www.stack.nl/~dimitri/doxygen/grouping.html) in doxygen for the "instances" of the concepts – Attila Apr 10 '12 at 14:10

score 1 · Answer 4 · answered Apr 21 '12 at 02:18

1

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.

answered Apr 21 '12 at 02:18

pmr

58,701
10
113
156

+1 because your answer helped me to reference my sections. – Adri C.S. Jan 02 '13 at 17:22

score 1 · Answer 5 · answered Jan 09 '16 at 20:38

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.

Documenting a C++ concept using doxygen?

5 Answers5