Fix doxygen configuraiton (#149)

FrankYFTang · web-flow · commit c743a28eecd1 · 2025-07-02T16:13:32.000-07:00
Here is why we fix the doxygen in this way.

I discussed with Gemini about how to fix this issue by asking

why doxygen cannot recognize class like class INFLECTION_CLASS_API inflection::dialog::NumberConcept ? how to fix it?

Gemini answered:

Doxygen's primary job is to parse C++, C, Java, Python, and other code to generate documentation. When Doxygen fails to recognize a class like class INFLECTION_CLASS_API inflection::dialog::NumberConcept, it's almost always due to the preprocessor macro INFLECTION_CLASS_API.

Here's why this happens and how to fix it:

Why Doxygen Cannot Recognize It

Preprocessor Macro Obscuring the Class Definition: Doxygen has a built-in preprocessor. If INFLECTION_CLASS_API is a macro that expands to something like __declspec(dllexport) (common for Windows DLLs) or __attribute__((visibility("default"))) (common for GCC/Clang on Linux/macOS), Doxygen's parser, by default, might not correctly interpret the resulting code. It sees __declspec(dllexport) class ... instead of class ....

ENABLE_PREPROCESSING = NO: If ENABLE_PREPROCESSING is set to NO in your Doxyfile, Doxygen won't process any macros, and it will simply see INFLECTION_CLASS_API as part of the class name, leading to a parsing error.

Macro Expansion Issues: Even with preprocessing enabled, Doxygen's default macro expansion behavior might not be sufficient. It might not expand INFLECTION_CLASS_API in a way that reveals the underlying class keyword to its parser.

How to Fix It

The solution involves configuring Doxygen's preprocessor to correctly handle the INFLECTION_CLASS_API macro.

Enable Preprocessing:
Make sure ENABLE_PREPROCESSING is set to YES in your Doxyfile.

Code snippet

ENABLE_PREPROCESSING = YES
Define the Macro in Doxygen:
You need to tell Doxygen what INFLECTION_CLASS_API means so it can effectively ignore or replace it during parsing. This is done using the PREDEFINED tag in your Doxyfile.

If INFLECTION_CLASS_API is empty (or should be ignored by Doxygen):
This is often the case for API macros where they expand to nothing for documentation builds.

Code snippet

PREDEFINED = INFLECTION_CLASS_API=
This tells Doxygen to replace INFLECTION_CLASS_API with nothing.

If INFLECTION_CLASS_API expands to a __declspec or __attribute__:
You need to remove these compiler-specific attributes.
For __declspec(dllexport) or __declspec(dllimport):

Code snippet

PREDEFINED = __declspec(x)=
This tells Doxygen to replace __declspec(anything) with nothing.

For __attribute__((visibility("default"))) or similar:

Code snippet

PREDEFINED = __attribute__(x)=
This tells Doxygen to replace __attribute__(anything) with nothing.

If INFLECTION_CLASS_API is a more complex macro:
If it's something like #define INFLECTION_CLASS_API SOME_OTHER_MACRO class, you might need to combine PREDEFINED with MACRO_EXPANSION and EXPAND_ONLY_PREDEF.

For example, if INFLECTION_CLASS_API itself expands to a simple empty string or a known attribute, the above methods should work. If it's more complex, you might need to use MACRO_EXPANSION = YES and EXPAND_ONLY_PREDEF = YES, then explicitly define INFLECTION_CLASS_API in PREDEFINED to be empty or a simple class keyword if it's truly hiding class. However, it's generally better to make the macro itself expand to an empty string for Doxygen.

Example PREDEFINED entry (most common scenario):

Code snippet

PREDEFINED = INFLECTION_CLASS_API= \
             __declspec(x)= \
             __attribute__(x)=
(Note the \ for multi-line definitions).

Run Doxygen in Debug Mode (Preprocessor Output):
If the above doesn't work, you can see exactly what Doxygen's preprocessor is doing by running Doxygen with the -d Preprocessor flag:

Bash

doxygen -d Preprocessor your_Doxyfile
This will print the preprocessed output to the console, allowing you to see how INFLECTION_CLASS_API is being handled and debug your PREDEFINED settings.

Steps to Implement the Fix:

Open your Doxyfile: This is the configuration file for your Doxygen project.

Locate ENABLE_PREPROCESSING: Ensure it's set to YES. If not, change it.

Locate PREDEFINED: Add or modify this tag.

Find out what INFLECTION_CLASS_API expands to in your actual build system (e.g., by looking at compiler preprocessor output or just checking the macro definition in your code).

Based on that, add the appropriate definition to PREDEFINED to effectively remove or normalize INFLECTION_CLASS_API for Doxygen.

Re-run Doxygen: After modifying the Doxyfile, run Doxygen again to generate the documentation.

By correctly configuring Doxygen's preprocessor to handle INFLECTION_CLASS_API, you should be able to get it to recognize your inflection::dialog::NumberConcept class.
diff --git a/inflection/docs/Doxyfile b/inflection/docs/Doxyfile
@@ -2373,15 +2373,15 @@ ENABLE_PREPROCESSING   = YES
 # The default value is: NO.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-MACRO_EXPANSION        = NO
+MACRO_EXPANSION        = YES
 
 # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES then
 # the macro expansion is limited to the macros specified with the PREDEFINED and
 # EXPAND_AS_DEFINED tags.
 # The default value is: NO.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-EXPAND_ONLY_PREDEF     = NO
+EXPAND_ONLY_PREDEF     = YES
 
 # If the SEARCH_INCLUDES tag is set to YES, the include files in the
 # INCLUDE_PATH will be searched if a #include is found.
@@ -2404,7 +2404,8 @@ INCLUDE_PATH           =
 # used.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-INCLUDE_FILE_PATTERNS  =
+INCLUDE_FILE_PATTERNS  = *.h \
+                         *.hpp
 
 # The PREDEFINED tag can be used to specify one or more macro names that are
 # defined before the preprocessor is started (similar to the -D option of e.g.
@@ -2414,7 +2415,8 @@ INCLUDE_FILE_PATTERNS  =
 # recursively expanded use the := operator instead of the = operator.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-PREDEFINED             =
+PREDEFINED             = INFLECTION_CLASS_API= \
+                         INFLECTION_CAPI=
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The
