Missing some classes in Doxygen docs

Started by Drifty Pine, 15 June 2021, 00:22:28

Drifty Pine

Hi Bruno,
Just a small heads-up: I noticed that some classes (for example, Gui and Canvas) seem to be missing the Doxygen generated docs that you show on the website for version 0.9.
I think this has to do with classes that are within #ifdef's you added when dealing with the SDL port.

texus

Thanks for letting me know. I guess I should enable the TGUI_HAS_BACKEND_SFML define next time I build the documentation.

For TGUI 0.9.3 I'm planning to rewrite the backends anyway, so I'll add a note that I have to look at improving the documentation (to make Gui classes from all backends show up).

Drifty Pine

My preferred way for dealing with this kind of thing is to do something like this in the code:
change: #ifdef TGUI_HAS_BACKEND_SFML
to: #if defined(TGUI_HAS_BACKEND_SFML) || defined(DOXYGEN)

This works because Doxygen automatically defines the macro DOXYGEN when it processes the files, just make sure you do not define the DOXYGEN macro anywhere in your code of course  :)

If you want both the #ifdef and an associated #else to be processed, you should also change any bare #else directives to be explicit #if's
so change:
#ifdef SOMETHING
  ...
#else
  ...
#endif

to:

#if defined(SOMETHING) || defined(DOXYGEN)
  ...
#endif

#if !defined(SOMETHING) || defined(DOXYGEN)
  ...
#endif

Two other ideas for dealing with this kind of thing in Doxygen is by editting the Doxyfile:
- use PREDEFINED = TGUI_HAS_BACKEND_SFML  and PREDEFINED = TGUI_HAS_BACKEND_SDL
  - This will define these both only for Doxygen, so you can leave your compile settings as they are.
  - However, this method won't include the code within both an #ifdef and any associated bare #else, so you would have change any of such #else to explicit #ifdef or #if defined(...).

- use ENABLE_PREPROCESSING = NO
  - This will disable all preprocessing, so you would get things within #ifdef and bare #else, but it might not be ideal because no preprocessing would be done at all.


texus

I didn't know about the DOXYGEN define, that might come in handy some day.

Once the new backend system is released I'll see whether it will be easier to put all backends in the PREDEFINED field or change the code to check DOXYGEN everywhere.

For now I was going to build only the documentation of the SFML backend (since this is what almost everyone used) by just adding the TGUI_HAS_BACKEND_SFML to the Doxyfile.
I just realized that it isn't enough those, the Gui class isn't missing because it is behind an ifdef like the Canvas class, it is missing because the directory containing the heading isn't part of INPUT. So I might wait until after 0.9.3 to determine which files need to be in the documentation (all of them probably, once I'm done reorganizing).

QuoteThis will define these both only for Doxygen, so you can leave your compile settings as they are
This reminds me that I should probably check other defines as well instead of leaving them to whatever the settings were on the last build. The TGUI_COMPILED_WITH_CPP_VER for example should probably be set when building the documentation so that any functionality with the latest c++ standard is always shown (e.g. for string_view conversion functions in String class).

Quotethis method won't include the code within both an #ifdef and any associated bare #else
I don't think that will be an issue, such cases shouldn't exist for the TGUI_HAS_BACKEND_XXX defines (and the few cases where they do exist are probably all inside the source code and not inside headers).