Ensure Doxygen documentation doesn't render files in drivers/builtin/include/mbedtls #281

New issue

Closed

opened 2025-05-06 07:52:29 -05:00 by felixc-arm · 0 comments

felixc-arm commented

2025-05-06 07:52:29 -05:00

(Migrated from github.com)

Change tfpsacrypto.doxyfile.in in TF-PSA-Crypto & mbedtls.doxyfile in mbedtls so that files in drivers/builtin/include/mbedtls are no longer rendered.

This task depends on https://github.com/Mbed-TLS/TF-PSA-Crypto/pull/247 being merged so that the public headers are under /include/mbedtls and are therefore rendered.

This work will also include changing Doxygen comments in other files so that the documentation builds without errors/warnings and does not contain any references to (newly) non-public content (i.e. macros/types/functions). See https://github.com/Mbed-TLS/TF-PSA-Crypto/pull/247#issuecomment-2851543251.

This task will likely need an mbedtls PR and a TF-PSA-Crypto PR, although they should be independent of eachother.

To build the Doxygen docs (at least for TF-PSA-Crypto as there is no CI job at the moment):
from tf-psa-crypto root

python3 scripts/config.py realfull
cd doxygen
rm -rf build-apidoc-full
mkdir build-apidoc-full
cd build-apidoc-full
cmake -DCMAKE_BUILD_TYPE:String=Check -DGEN_FILES=ON ../../
make tfpsacrypto-apidoc

and then open apidoc/index.html in a browser. (n.b. The warnings that will cause the CI to fail are not very obvious in the wall of build logs.)

Change `tfpsacrypto.doxyfile.in` in `TF-PSA-Crypto` & `mbedtls.doxyfile` in `mbedtls` so that files in `drivers/builtin/include/mbedtls` are no longer rendered. This task depends on https://github.com/Mbed-TLS/TF-PSA-Crypto/pull/247 being merged so that the public headers are under `/include/mbedtls` and are therefore rendered. This work will also include changing Doxygen comments in other files so that the documentation builds without errors/warnings and does not contain any references to (newly) non-public content (i.e. macros/types/functions). See https://github.com/Mbed-TLS/TF-PSA-Crypto/pull/247#issuecomment-2851543251. This task will likely need an `mbedtls` PR and a `TF-PSA-Crypto` PR, although they should be independent of eachother. To build the Doxygen docs (at least for TF-PSA-Crypto as there is no CI job at the moment): from `tf-psa-crypto` root ``` python3 scripts/config.py realfull cd doxygen rm -rf build-apidoc-full mkdir build-apidoc-full cd build-apidoc-full cmake -DCMAKE_BUILD_TYPE:String=Check -DGEN_FILES=ON ../../ make tfpsacrypto-apidoc ``` and then open `apidoc/index.html` in a browser. (n.b. The warnings that will cause the CI to fail are not very obvious in the wall of build logs.)

No milestone

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

gh-Mbed-TLS/TF-PSA-Crypto#281

No description provided.

Rows
Columns