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>
diff --git a/doxygen/mbedtls.doxyfile b/doxygen/mbedtls.doxyfile
index 7c4f31c..1ad5866 100644
--- a/doxygen/mbedtls.doxyfile
+++ b/doxygen/mbedtls.doxyfile
@@ -25,3 +25,15 @@
DOT_GRAPH_MAX_NODES = 200
MAX_DOT_GRAPH_DEPTH = 1000
DOT_TRANSPARENT = YES
+
+# Doxygen accepts empty descriptions for commands such as \retval,
+# but clang -Wdocumentation doesn't (since Clang 15, for \retval).
+# https://github.com/Mbed-TLS/mbedtls/issues/6960
+# https://github.com/llvm/llvm-project/issues/60315
+# As a workaround, when documenting the status codes that a function can
+# return, if you don't have anything to say beyond the status code's
+# description, you can write something like
+# \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
+# This does not change the documentation generated by Doxygen, but
+# it pacifies clang -Wdocumentation.
+ALIASES += emptydescription=""