Discussion on improved doxygen documentation for generated code

[tmadlener]

This came up during todays meeting in the context of an improved documentation for EDM4Hep. The currently generated doxygen documentation lists all of the classes that are generated, which can be a bit overwhelming for newcomers or users who simply want to use EDM4Hep without having to worry about the "implementation details" of podio (e.g. the Obj and Data classes or all the different Iterators that are present). It would be nice to have some sort of grouping of the different classes into a "user interface" and "podio implementation classes".

One possibility would be to put all the podio layer classes into a separate (sub)namespace, which would make the grouping by namespaces trivial in doxygen (and also would be visible in the code). Another possibility could be to investigate how doxygen can be configured to group the different classes and potentially add the necessary things to the generated classes (e.g. labels).

A slightly different topic is the fact that currently only the user facing and the Data classes actually document their members, while the podio implementation classes in general do not. Also this could be improved.

[tmadlener]

Possible solutions:

• Namespaces for grouping
• Using doxygen groups
• Filter out things using doxygen