Improve documentation of documentation workaround
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
diff --git a/doxygen/mbedtls.doxyfile b/doxygen/mbedtls.doxyfile
index 7e8d196..1077f86 100644
--- a/doxygen/mbedtls.doxyfile
+++ b/doxygen/mbedtls.doxyfile
@@ -32,10 +32,13 @@
# 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
+# We often use \retval declarations with just a constant name to
+# document which error codes a function can return. If the documentation
+# of the error code is enough to explain the error, then an empty
+# description on the \retval statement is ok. However, the source code
+# of the description needs to be made non-empty to pacify Clang.
+# In such cases, 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=""