Improve documentation of documentation workaround

Signed-off-by: Gilles Peskine <[email protected]>

doxygen/mbedtls.doxyfile

@@ -30,10 +30,13 @@ DOT_TRANSPARENT        = YES
 # 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=""