tree 00fea1dfa065b8abdcb9ad903c6dfa1477b376a2
parent 319a5675db31f47b8bc006fcff101928403b68a1
author Gilles Peskine <Gilles.Peskine@arm.com> 1676398540 +0100
committer Gilles Peskine <Gilles.Peskine@arm.com> 1676398540 +0100

Define a workaround for empty \retval description

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>