Doxygen does not generate documentation for commented-out macros

[jethrogb]

When comparing https://tls.mbed.org/api/config_8h.html with include/mbedtls/config.h a lot of macros are missing. In fact, all macros that are shipped commented-out do not appear in the online documentation.

[ciarmcom]

ARM Internal Ref: IOTSSL-837

[pjbakker]

This is unfortunately one of doxygen's known "issues".
Solutions we are aware of are not so pretty (require a #ifdef DOXYGEN around each define or a single block at the end of config.h). If somebody knows a way to let doxygen show what it calls 'documentation for unknown defines', that would be awesome :)

[gilles-peskine-arm]

The online documentation is (or should be) generated after config.py realfull (or config.pl realfull in older versions). This uncomments most definitions, but not the ones in the “Module configuration options”, which are explicitly excluded even from realfull.

As a result, the online documentation is missing a number of configuration options:

<include/mbedtls/config.h perl -l -ne 'if (m!^[/ ]*#define (\w+)!) { system("grep -q $1 apidoc/globals_defs_m.html") and print $1 }'
MBEDTLS_CONFIG_H
_CRT_SECURE_NO_DEPRECATE
MBEDTLS_ECP_MAX_BITS
MBEDTLS_ECP_WINDOW_SIZE
MBEDTLS_ECP_FIXED_POINT_OPTIM
MBEDTLS_PLATFORM_STD_MEM_HDR
MBEDTLS_PLATFORM_STD_CALLOC
MBEDTLS_PLATFORM_STD_FREE
MBEDTLS_PLATFORM_STD_EXIT
MBEDTLS_PLATFORM_STD_TIME
MBEDTLS_PLATFORM_STD_FPRINTF
MBEDTLS_PLATFORM_STD_PRINTF
MBEDTLS_PLATFORM_STD_SNPRINTF
MBEDTLS_PLATFORM_STD_EXIT_SUCCESS
MBEDTLS_PLATFORM_STD_EXIT_FAILURE
MBEDTLS_PLATFORM_STD_NV_SEED_READ
MBEDTLS_PLATFORM_STD_NV_SEED_WRITE
MBEDTLS_PLATFORM_STD_NV_SEED_FILE
MBEDTLS_PLATFORM_CALLOC_MACRO
MBEDTLS_PLATFORM_FREE_MACRO
MBEDTLS_PLATFORM_EXIT_MACRO
MBEDTLS_PLATFORM_TIME_MACRO
MBEDTLS_PLATFORM_TIME_TYPE_MACRO
MBEDTLS_PLATFORM_FPRINTF_MACRO
MBEDTLS_PLATFORM_PRINTF_MACRO
MBEDTLS_PLATFORM_SNPRINTF_MACRO
MBEDTLS_PLATFORM_VSNPRINTF_MACRO
MBEDTLS_PLATFORM_NV_SEED_READ_MACRO
MBEDTLS_PLATFORM_NV_SEED_WRITE_MACRO
MBEDTLS_SSL_CIPHERSUITES
MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_CERTIFICATES
MBEDTLS_PLATFORM_ZEROIZE_ALT
MBEDTLS_PLATFORM_GMTIME_R_ALT
MBEDTLS_ECDH_VARIANT_EVEREST_ENABLED

The first 2 are false positives, and some of these macros don't have any documentation (but I think still should be shown in the index), but others have documentation that's not getting included, e.g. MBEDTLS_PARAM_FAILED.

Symbols from the “Module configuration options” are only documented if the macro is defined in another header in include/*/*.h without a precondition that the realfull config doesn't meet.

Furthermore, the documentation from config.h is only included if it starts with a \def macro. Blocks that don't start with \def end up being attached to the next block, e.g. the documentation of MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_CERTIFICATES (off in realfull) ends up being part of the documentation of MBEDTLS_TLS_DEFAULT_ALLOW_SHA1_IN_KEY_EXCHANGE below (on in realfull).

Arguably some of these options should be in the “mbed TLS feature support” section instead. We seem to consistently use the feature support section for features such that enabling the option only enables the feature, and the module configuration option section for non-boolean options, but I don't see a pattern for on/off options that change the default behavior. But this wouldn't solve the problem since it also affects some non-boolean options.

@mpg As the creator of realfull (1989caf), do you remember by any chance why it excludes “Module configuration options”?

---

Enabling “Module configuration options” in realfull (like #965 does in docfull) would resolve both the missing items from the documentation and the misattached blocks without \def. However, it causes some text to be duplicated, with lines in config.h that duplicate the documentation in another module, e.g. the exact same line except for leading // is in both config.h and ssl.h, so uncommenting the line in config.h results in the description of MBEDTLS_SSL_COOKIE_TIMEOUT being two identical sentences.

#define MBEDTLS_SSL_COOKIE_TIMEOUT        60 /**< Default expiration delay of DTLS cookies, in seconds if HAVE_TIME, or in number of cookies issued */

---

Note added in 2024: I can't reproduce the statement above. The definition of #define MBEDTLS_SSL_COOKIE_TIMEOUT in ssl_cookie.h has to be guarded by !defined(MBEDTLS_SSL_COOKIE_TIMEOUT), otherwise it would be impossible to set it to a different value in the configuration file. But that means Doxygen skips the definition in ssl_cookie.h when the one in config.h is uncommented. I'm not sure why I made the statement above, it looks like something I'd have written after experimentation, but now I can't figure out what I did/thought in 2020.

[mpg]

I'm not sure what the reasoning was when "realfull" was created, or even if there was an explicit intention of excluding "Module configuration options" or it just happened that way because that's what "full" was doing already and "realfull" was implemented as a variant of it.

What I can tell you is that when reading the description of this issue, my first reaction was "but aren't those options supposed to be documented in their respective modules?" Then I checked the ECP-related options. Turns out MBEDTLS_ECP_MAX_BITS is indeed documented in ecp.h, but the other two are not - actually, it looks like I meant to document them but forgot the /** at the beginning of the comment...

As you note, that's not an isolated case and a few other module options are documented in their module instead of / in addition to config.h. Perhaps we could make it a rule that such options are documented in their module, with config.h containing stub documentation such as see ecp.h to keep doxygen happy?

Actually there are (at least) two kinds of macros here:

• some macros, such as MBEDTLS_ECP_MAX_BITS are always going to be defined: if config.h doesn't define them, then ecp.h will - for those, the strategy of pointing to ecp.h should work;
• some other macros can stay undefined, for example all of the MBEDTLS_PLATFORM_xxx_MACRO will not be defined by platform.h is config.h doesn't define them - for those, we probably need the documentation to be in config.h.