-
Notifications
You must be signed in to change notification settings - Fork 72
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
[Discussion] Improving the Doxygen API #1059
Comments
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: 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. |
We discussed the topic in the meeting today and found some points: #1080 |
What is left to do here that is not part of #1080? If there is nothing left, can we close this issue? |
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 |
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.
So you will continue to work on this issue? Then I will assign it to you! |
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. [update] one problem of alpakas doxygen is that we do not comment functions and therefore you mostly see only the function signatures. |
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. |
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:
@psychocoderHPC's idea:
The text was updated successfully, but these errors were encountered: