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>
* Change "source code documentation" to "API documentation" for
precision
* Change "mbed TLS" to "Mbed TLS" following established convention
* Use title case in the title
Signed-off-by: David Horstmann <david.horstmann@arm.com>
Since the API docs are now published as part of the larger
documentation, it makes no sense to give an overview of Mbed TLS in the
mainpage as this is already given elsewhere.
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>
