Skip to content

doxygen: fix and improve macro expansion configuration options #1353

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

Merged
merged 1 commit into from
Mar 17, 2025

Conversation

eramongodb
Copy link
Contributor

@eramongodb eramongodb commented Mar 14, 2025

Workaround doxgyen/doxygen#11495 and doxygen/doxygen#11496 which are affecting CXX-2745 API documentation by tidying up the preprocessor-related Doxygen configuration options following #1301. Since all relevant macro definitions are now visible, they can be expanded as-is with MACRO_EXPANSION = YES without using EXPAND_AS_DEFINED.

EXPAND_ONLY_PREDEF = YES and SKIP_FUNCTION_MACROS = YES are no longer required to guard against the attempted expansion of complex macros, as all problematic expansions are already being guarded with \cond DOXYGEN_DISABLE (these options do not help us avoid these issues) and we do not parse non-header files (where most other macros, including those from external libraries, are used).

Due to the complexity of export macro definitions confusing the Doxygen preprocessor (notably their expansion into __attribute__ and __declspec specifiers), PREDEFINED is used to replace the definitions of *_ABI_EXPORT, *_ABI_CDECL, and *_ABI_EXPORT_CDECL with simpler alternatives. All three must be predefined to fully avoid preprocessor and parser failures.

Given the *_ABI_EXPORT= predefinitions, the *_ABI_EXPORT macro is never defined in code due to the #ifndef guard in the generated export header. A Doxygen preprocessor branch which unconditionally defines the export macro (as a stub: ...) is needed to satisfy the \def special command's requirement that the documented macro is defined in code prior to the doc comment.

@eramongodb eramongodb requested a review from kevinAlbs March 14, 2025 21:21
@eramongodb eramongodb self-assigned this Mar 14, 2025
@eramongodb eramongodb merged commit 05996a5 into mongodb:master Mar 17, 2025
19 of 20 checks passed
@eramongodb eramongodb deleted the cxx-doxygen branch March 17, 2025 14:56
eramongodb added a commit to eramongodb/mongo-cxx-driver that referenced this pull request Mar 17, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants