Where should we document concepts?

[Markus Ringnér]

Let me give an example of what is to be discussed. We have:

template <typename Distance>
class NCC : public SupervisedClassifier

NCC has some requirements on classes passed as Distance. In often used termininology, Distance is a concept. We have classes such as EuclideanDistance that implement the Distance concept. Of course we have other classes implementing Distance and also classes other than NCC that depend on the concept. So where should we document concepts. In NCC we should document that Distance should fulfill the "Distance concept" and in EuclideanDistance we should document that it implements the "Distance concept". But where should we document the "Distance concept"? Our documentation is based on writing the documentation in the corresponding file with the code. But no code files correspond to concepts (in C++).

[Peter]

I think we should do this in Doxygen.

Let's add a file doc/concepts.doxygen and let Doxygen parse the fuile by updating doxygen.config.

One way to do this is to use \page command in Doxygen (see ​http://www.stack.nl/~dimitri/doxygen/commands.html#cmdpage)

In doc/concept.doxygen one could for example write

/**
 \page concept_distance Distance

  \section Description
  A Distance is a...

  \section Requirements
  
*/	

and then in class documentation one can refer to Distance by \ref concept_distance

[Markus Ringnér]

In [1069] I implemented some attempts along Peter's suggestions. A concepts.doxygen page was added with a page for the concept Distance. References to the concept Distance were added to the classes EuclideanDistance and PearsonDistance. A few questions remains:

• Is this solution ok with Jari?
• Class names written in concepts.doxygen do not automatically become links to the documentation for the class. This is also true for namespaces.doxygen. Whereas they become links when they are written in documentation in *.h files. So how to make links to for example documentation of classes in concepts.doxygen?
• The concepts end up together will all other potential other additional documentation under "Related pages" in the documentation. Is it possible to generate a top-level header called concepts? If so do we want such a thing or is "related pages" ok?
• Maybe this should not be mentioned here, but how should one avoid generating links? Now there is a link to the Pearson class from PearsonDistance because Pearson is written in the documentation, but the link is misleading and should be avoided.

[Markus Ringnér]

• Maybe this should not be mentioned here, but how should one avoid generating links? Now there is a link to the Pearson class from PearsonDistance because Pearson is written in the documentation, but the link is misleading and should be avoided.

I finally found out that this is avoided by putting % in front of the word.

[Markus Ringnér]

Replying to markus:

• Class names written in concepts.doxygen do not automatically become links to the documentation for the class. This is also true for namespaces.doxygen. Whereas they become links when they are written in documentation in *.h files. So how to make links to for example documentation of classes in concepts.doxygen?

I realized one has to add the full classname with all namespaces for this to work since the concept is documented in a separate page and not inside code residing in a namespace. So theplu::yat::statistics::PearsonDistance becomes a link automatically in the page environment but not PearsonDistance.

[Jari Häkkinen]

Replying to markus:

In [1069] I implemented some attempts along Peter's suggestions. A concepts.doxygen page was added with a page for the concept Distance. References to the concept Distance were added to the classes EuclideanDistance and PearsonDistance. A few questions remains:

• Is this solution ok with Jari?

Yes

[Markus Ringnér]

• The concepts end up together will all other potential other additional documentation under "Related pages" in the documentation. Is it possible to generate a top-level header called concepts? If so do we want such a thing or is "related pages" ok?

In [1074] I changed so Concepts now becomes one item under 'Related pages'. I think this should suffice: all concepts are listed on the Concepts page, which is not its own leaf in the top level header, but Concepts is at least a single page on 'Related pages'.

[Markus Ringnér]

Now I think all the issues in the list above has been resolved.

To add documentation for a new concept two things should be done (in addition to referring to the concept in places where it is used):

• Add a doxygen page describing the concept in concepts.doxygen.
• Add a subpage to the concept from the doxygen concept page in concepts.doxygen

[Peter]

Replying to markus:

Replying to markus:

• Class names written in concepts.doxygen do not automatically become links to the documentation for the class. This is also true for namespaces.doxygen. Whereas they become links when they are written in documentation in *.h files. So how to make links to for example documentation of classes in concepts.doxygen?

I realized one has to add the full classname with all namespaces for this to work since the concept is documented in a separate page and not inside code residing in a namespace. So theplu::yat::statistics::PearsonDistance becomes a link automatically in the page environment but not PearsonDistance.

Is it possible to put this kind of documentation in a namespace? For example could one write

namespace theplu {
namespace yat {

*** statistics::PearsonDistance is a Concept bla bla ***

}}

If it is possible, I'm not sure it will be preferable, but I am curious...

[Peter]

Replying to markus:

• The concepts end up together will all other potential other additional documentation under "Related pages" in the documentation. Is it possible to generate a top-level header called concepts? If so do we want such a thing or is "related pages" ok?

In [1074] I changed so Concepts now becomes one item under 'Related pages'. I think this should suffice: all concepts are listed on the Concepts page, which is not its own leaf in the top level header, but Concepts is at least a single page on 'Related pages'.

To create our own tab 'Concepts' we have to hack a html-header, I guess.

[Markus Ringnér]

Replying to peter:

Replying to markus:

Replying to markus:

• Class names written in concepts.doxygen do not automatically become links to the documentation for the class. This is also true for namespaces.doxygen. Whereas they become links when they are written in documentation in *.h files. So how to make links to for example documentation of classes in concepts.doxygen?

I realized one has to add the full classname with all namespaces for this to work since the concept is documented in a separate page and not inside code residing in a namespace. So theplu::yat::statistics::PearsonDistance becomes a link automatically in the page environment but not PearsonDistance.

Is it possible to put this kind of documentation in a namespace? For example could one write

namespace theplu {
namespace yat {

*** statistics::PearsonDistance is a Concept bla bla ***

}}

If it is possible, I'm not sure it will be preferable, but I am curious...

I saw examples of people doing similar things and there are some ugly consequences, which is why I did not pursue it. For example, now only *.h files are considered to be code by our doxygen.config, so either we would have to put this documentation in .h files even though it is not code (well the namespaces are there, but we do not want the compiler to see these files) or we would have to say that .doxygen files are source-files through FILE_PATTERNS in doxygen.config. The negative aspect of both alternatives is that we in the documentation get a "code file" for the concept to click on that makes no sense: doxygen does not show doxygen comments in code files so in this case essentially only the Id-string ends up here, which is what I got, and maybe a couple of namespace lines if we add these. I tested it this far and found it ugly. Others have then hacked doxygen to make it produce nicer things for their own metatags put in similar files, but I do not think it is worth the effort in this case (and we do not want to up2date and distribute a hacked doxygen).

Anyway, I am not sure a concept necessarily belongs in a namespace as one can make implementations of it in any namespace one wants. Maybe it is different in C++0x when concepts are seen by the compiler.

[Markus Ringnér]

Replying to peter:

Replying to markus:

• The concepts end up together will all other potential other additional documentation under "Related pages" in the documentation. Is it possible to generate a top-level header called concepts? If so do we want such a thing or is "related pages" ok?

In [1074] I changed so Concepts now becomes one item under 'Related pages'. I think this should suffice: all concepts are listed on the Concepts page, which is not its own leaf in the top level header, but Concepts is at least a single page on 'Related pages'.

To create our own tab 'Concepts' we have to hack a html-header, I guess.

Yes, I saw people doing that too, so maybe we should do that one day when we get a lot of concepts. As it is now I guess most people will click from a class documentation to a specific concept anyway.