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>
