How to tell Doxygen to process an #include within a class definition

[itavero]

In our code base, we generated several base classes as part of our build process, which we inherit from to implement application logic (the generated classes take care of the "infrastructure").
In order not to repeat our selves to often, the tool also generates .inc file, which looks something like:

/**
 * @file some_component_gen.inc
 */

// ***** THIS FILE IS GENERATED. DO NOT MODIFY! *****

public:
  void OnComponentsLoaded() final;
  void OnTimerElapsed() final;

This basically lists all the function we need to override from the generated base class, so we do not have to repeat that again in our class that inherits from it. Instead, we include this .inc file within the class declaration:

/* .. there's more in this file, but just to give you an idea about the usage .. */
namespace components {
class SomeComponent : public BaseSomeComponent {
private:
  void SomethingInternal();

public:
  /* constructor and stuff here */

/* lastly we include the .inc file */
#include "some_component_gen.inc"
};
} // namespace components

This works just fine for us, but now we are trying to generate documentation and I see a lot of warnings that look like:

warning: no uniquely matching class member found for 
void component::SomeComponent::OnComponentsLoaded()
Possible candidates:
  void component::BaseSomeComponent::OnComponentsLoaded()
  void component::BaseSomeOtherComponent::OnComponentsLoaded()
  void component::BaseYetAnotherComponent::OnComponentsLoaded()

As input in the configuration file (I use CMake to generate it via the doxygen_add_docs function it offers), I have a combination of the following:

• Include directories
• File paths to source files
• File paths to header files
• File paths to these .inc files.

I also added an EXTENSION_MAPPING = .inc=C++, after I learned that Doxygen treats .inc files as PHP by default.
I've attached a redacted version of the Doxygen configuration file as a reference.

My question of course is, how do I have Doxygen parse these .inc files correctly in the location they are #included?

[albert-github]

Difficult problem as doxygen is not a compiler and does only a limited amount of preprocessing.
For the documentation parts there are some features (like: \include... and \snippet...) but for the "bare" code they are not really there (only e.g. #defines are filtered).
Only possibilitiesy I see:

• is to include these line by means of the FILTER_PATTERNS etc. into doxygen. The later will break the line number counting and consequently the line numbers in e.g. warnings (so some internal commands have to be used as well)
• rewrite the .inc file to e.g.

  /**
  * @file some_component_gen.inc
  */
  
  // ***** THIS FILE IS GENERATED. DO NOT MODIFY! *****
  
  #define some_component_gen \
  public: \
   void OnComponentsLoaded() final; \
   void OnTimerElapsed() final;
  

  and "change" the include statement from:

  #include "some_component_gen.inc"
  

  to

  #include "some_component_gen.inc"
  some_component_gen
  

[itavero]

For now I used the first workaround you suggested, but if the regression that occurred in version 1.8.16 can be resolved, that would be even better of course.

[doxygen]

@albert-github This actually used to work (try for instance Doxygen version 1.8.9), where any #include inside a {...} was treated specially and did an actually include just like the preprocessor would. Somewhere between 1.8.9 and 1.8.20 this feature got lost it seems...

[albert-github]

Looks like the problem is introduced between versions 1.8.15 and 1.8.16 and to be more precise (checked with the executables I had lying around):

• June 2, 2019 7403c9e is OK
• June 10, 2019 572035f is WRONG

So I suspect the change (047df30 ):

Commit: 047df30104f628bdfbbe71fbc8d11440a5b0494a [047df30]
Date: Sunday, June 2, 2019 1:46:31 PM

issue #7021 Warning about missing item in INCLUDE_PATH

Do the `curlyCount` per file and not globally.

to be responsible.
Might be that we need some special handling for extern "C" {

A related issue might be: #10272

[itavero]

That issue indeed shows the same problem as far as I can tell.

[doxygen]

@itavero I've just pushed a fix for this, see commit 6ae0631. Let me know if this works for you.

[itavero]

I just tried v1.16.1 as well and I also see the issue there. Let me check if something in our build tooling changed that may have caused this.

[itavero]

Interestingly, with 1.12.0 (c73f5d3) it also doesn't work.

In the mean time, with the help of an LLM, I also went through the history of the relevant sources in our code base, but so far the few differences I did see did not influence the results (I tried reverting those changes and running Doxygen again, yielding the same warnings).

Of course, at the time I tested with the build of 9152d39 so perhaps something else changed.
I'm not sure if I ever did a retest with the actual release when integrating it (I'm starting to doubt that now).

[albert-github]

Did you try the example I attached with a plain doxygen version i.e. just stating doxygen ?

[itavero]

I tried the example which worked correctly, and after a lot of bisecting our repositories history starting from July 2024, I finally found that there was an faulty change introduced in our Doxygen configuration.
Somehow a pattern ended up in EXCLUDE_PATTERNS that caused our .inc files to be excluded.

So sorry to have bothered you for this. I am really thankful for your quick response though.

[albert-github]

@itavero
Thanks, most important is that the problem is solved