Otherwise Doxygen complains about two `\file` with the same name.
This is a temporary exclusion which can be removed once crypto no longer has
an oid.h.
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
In our tests, we run `tests/scripts/doxygen.sh`, which checks that `doxygen`
runs without warnings after `scripts/config.py realfull`. In this
configuration, alternative implementations such as `MBEDTLS_RSA_ALT` are
enabled, which allows the documentation to contain references to the
`MBEDTLS_xxx_ALT` symbol itself. However, this disables context types that
alternative implementations must define in their header, such as
`mbedtls_rsa_context`. See https://github.com/Mbed-TLS/mbedtls/issues/4518
As a partial fix, allow `tests/scripts/doxygen.sh` to see dummy definitions
of the context type. This way, we can use both `#MBEDTLS_RSA_ALT` and
`#mbedtls_rsa_context` cross-references in our documentation. This is not
ideal, because `doxygen.sh` isn't testing for errors in the documentation of
the affected context types, but it's cheap progress.
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
The official spelling of the trade mark changed from all-lowercase "mbed"
to normal proper noun capitalization "Mbed" a few years ago. We've been
using the new spelling in new text but still have the old spelling in a
lot of text. This commit updates most occurrences of "mbed TLS":
```
sed -i -e 's/mbed TLS/Mbed TLS/g' $(git ls-files ':!ChangeLog' ':!tests/data_files/**' ':!tests/suites/*.data' ':!programs/x509/*' ':!configs/tfm*')
```
Justification for the omissions:
* `ChangeLog`: historical text.
* `test/data_files/**`, `tests/suites/*.data`, `programs/x509/*`: many
occurrences are significant names in certificates and such. Changing
the spelling would invalidate many signatures and tests.
* `configs/tfm*`: this is an imported file. We'll follow the upstream
updates.
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
Sphinx's breathe plugin cannot readily parse the Mbed TLS macros, so
define the less essential ones away at the doxygen step to reduce the
number of warnings.
Signed-off-by: David Horstmann <david.horstmann@arm.com>
Sphinx's breathe plugin cannot readily parse the Mbed TLS macros, so
define the less essential ones away at the doxygen step to reduce the
number of warnings.
Signed-off-by: David Horstmann <david.horstmann@arm.com>
Since Clang 15, `clang -Wdocumentation` warns about an empty description in
a Doxygen `\retval` command:
```
include/psa/crypto.h:91:23: error: empty paragraph passed to '\retval' command [-Werror,-Wdocumentation]
* \retval #PSA_SUCCESS
~~~~~~~~~~~~~~~~~~~^
```
Ideally `\retval` directives should have a description that describes the
precise meaning of the return value, but we commonly use an empty
description when the return value is a status code and the status code's
description is sufficient documentation.
As a workaround, define a Doxygen command `\emptydescription` that we can
use to make the description source code non-empty, without changing the
appearance. Using the command will be done in a subsequent commit.
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
None of these options had any impact on the generated output.
Checked after turning off the HTML_TIMESTAMP option
and running sha256sum <(find . -type f -exec sha256sum {} \; | sort) in
the apidoc directory.
Signed-off-by: Andrzej Kurek <andrzej.kurek@arm.com>
Executed ./scripts/bump_version.sh --version 2.25.0 --so-crypto 6
Increasing the SO version of the crypto library, because the openless
API improvement came with API/ABI incompatibilities. For example
- the size of psa_key_handle_t changed
- the type of a parameter in 18 public functions has changed from
psa_key_handle_t to mbedtls_svc_key_id_t
Signed-off-by: Janos Follath <janos.follath@arm.com>
Executed "./scripts/bump_version.sh --version 2.23.0 --so-crypto 5"
A symbol has been removed from the mbedcrypto library since the last
release:
mbedtls_ecc_group_to_psa ( enum mbedtls_ecp_group_id grpid,
size_t* bits )
This is an ABI break and we need to increase the SO version.
Signed-off-by: Janos Follath <janos.follath@arm.com>
Previously, doxygen was unable to effectively use preprocessing to determine
which parts of code should be documented. This was due to its inability to
include headers during preprocessing, which was discovered by running it in
preprocessing debug mode:
doxygen -d preprocessor mbedtls.doxyfile
An example of failure: "#include mbedtls/config.h: not found! skipping..."
With the following fix includes are properly preprocessed with the documentation
being considerably larger.
Signed-off-by: Andrzej Kurek <andrzej.kurek@arm.com>
