Doxygen: Only render public files

[felixc-arm]

mbedtls part of and resolves Mbed-TLS/TF-PSA-Crypto#281

Changes doxygen so that only files in ./include, ./tf-psa-crypto/include, and ./tests/include/alt-dummy are rendered (i.e. only public files).

You may notice that ./drivers/builtin/include is still present in INCLUDE_PATH in the doxyfile. According to doxygen documentation: "The INCLUDE_PATH tag can be used to specify one or more directories that contain include files that are not input files but should be processed by the preprocessor."

In practice, removing this gave weird results, e.g. some macros like MBEDTLS_PSA_HMAC_OPERATION_INIT from crypto_builtin_composites.h were not available in the documentation, and it thought that MBEDTLS_PRIVATE was a function with a few different signatures, so it seems to be correct to leave it.

As the mbedtls CI has a readthedocs build, the resulting changes should be viewable there.

PR checklist

Please remove the segment/s on either side of the | symbol as appropriate, and add any relevant link/s to the end of the line.
If the provided content is part of the present PR remove the # symbol.

• changelog not required because: Documentation change, covered under overall documentation about public/private headers
• development PR provided: HERE
• TF-PSA-Crypto PR provided: Doxygen: Only render public files TF-PSA-Crypto#305
• framework PR not required
• 3.6 PR not required because: 4.0/1.0 change only
• tests not required because: documentation change

[gilles-peskine-arm]

You may notice that ./drivers/builtin/include is still present in INCLUDE_PATH in the doxyfile. According to doxygen documentation: "The INCLUDE_PATH tag can be used to specify one or more directories that contain include files that are not input files but should be processed by the preprocessor."

In practice, removing this gave weird results, e.g. some macros like MBEDTLS_PSA_HMAC_OPERATION_INIT from crypto_builtin_composites.h were not available in the documentation, and it thought that MBEDTLS_PRIVATE was a function with a few different signatures, so it seems to be correct to leave it.

Yes, I think that makes sense.

I'm not actually sure we want MBEDTLS_PRIVATE expanded. After all, a private field foo should be undocumented, not documented under the name private_foo. But that's not related to the repository split or to the API changes, it's a preexisting quality issue, so it's not particularly relevant for the 1.0/4.0 release. And anyway the correct solution would be more complicated than just leaving MBEDTLS_PRIVATE unexpanded, since as you note this understandably confuses Doxygen.

[mpg]

Pre-existing and unrelated - question: why is ../tests/include/alt-dummy here? I find it surprising to have something from tests in the public rendered documentation.

[gilles-peskine-arm]

See 5186014

[gilles-peskine-arm]

By the way, alt-dummy probably shouldn't be needed anymore, since we've removed MBEDTLS_xxx_ALT. But that's a post-1.0 cleanup.

[felixc-arm]

Quick rebase to remove tf-psa-crypto conflict, unfortunately couldn't remove the tf-psa-crypto pointer commit entirely as the pre-work has not been picked up in another commit yet.

[mpg]

LGTM, thanks!

[gilles-peskine-arm]

LGTM