[Discussion] Improving the Doxygen API

[SimeonEhrig]

During the workshop today, there was question about the best practice of using the Doxygen documentation. In my opinion it's hard to read the documentation, in special if you are not familiar with concepts like traits.

This issue is about ideas for improving the documentation an it pros and cons.

My idea:

• separate the documentation in public and internal API and hide the internal API (if Doxygen allow this)

@psychocoderHPC's idea:

• add documentation to the Sphinx Doc, how to use the Doxygen documentation ( for example explaining the trait classes)

[j-stephan]

add documentation to the Sphinx Doc, how to use the Doxygen documentation

Yo dawg, I heard you like documentation...

In all seriousness, maybe we could add an API reference to the Sphinx doc? Containing only the parts that are relevant for alpaka users. Maybe auto-generate it and then strip the internal parts by hand.

[SimeonEhrig]

add documentation to the Sphinx Doc, how to use the Doxygen documentation

Yo dawg, I heard you like documentation...

In all seriousness, maybe we could add an API reference to the Sphinx doc? Containing only the parts that are relevant for alpaka users. Maybe auto-generate it and then strip the internal parts by hand.

We already have the technical possibility and use it to link the Doxygen API in Sphinx Doc:
https://alpaka.readthedocs.io/en/latest/usage/implementation/mapping/CUDA.html
https://github.com/alpaka-group/alpaka/blob/develop/docs/source/usage/implementation/mapping/CUDA.rst

But in this case we need an extra page and we have to make sure that the user reads the page before reading the Doxygen Doc. So maybe a hint in the Doxygen is necessary.

[SimeonEhrig]

We discussed the topic in the meeting today and found some points: #1080

[bernhardmgruber]

What is left to do here that is not part of #1080? If there is nothing left, can we close this issue?

[SimeonEhrig]

Do you use the doxygen documentation? I don't use it, because I have no idea where to start. I use a combination of examples, auto completion and René.

It's on my do list, to check what I can improve in doxygen, also for vikunja: alpaka-group/vikunja#65

[bernhardmgruber]

Do you use the doxygen documentation? I don't use it, because I have no idea where to start. I use a combination of examples, auto completion and René.

I don't use it either because I am that kind of guy that uses Ctrl-click and jump into the implementation headers and start reading. Very often I also need to read the implementation because the documentation leaves out the details I am looking for.

But Doxygen could still be very useful for some users, so we should provide it and make sure it is up-to-date and clean.

It's on my do list, to check what I can improve in doxygen, also for vikunja: alpaka-group/vikunja#65

So you will continue to work on this issue? Then I will assign it to you!

[psychocoderHPC]

Doxygen can be very useful because you get an overview of namespaces. The problem is that is very hard to see for the user which namespace is for users and which is internal. Maybe we need an independent namespace for internal stuff a user never touches directly.
I use mostly https://alpaka-group.github.io/alpaka/namespacealpaka.html to start looking into the code in cases I do not check the headers directly. In foreign projects, I start with the namespace overview too if the project is shipping a Doxygen documentation.

[update] one problem of alpakas doxygen is that we do not comment functions and therefore you mostly see only the function signatures.

[SimeonEhrig]

But Doxygen could still be very useful for some users, so we should provide it and make sure it is up-to-date and clean.

I don't want to throw away. But some parts are missing, like @psychocoderHPC already mentioned. For me, it is hart to "connect" the data types, functions and structs to a working application.