Skip to content

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