diff --git a/doxygen/mbedtls.doxyfile b/doxygen/mbedtls.doxyfile
index 7e8d19611..1077f86db 100644
--- a/doxygen/mbedtls.doxyfile
+++ b/doxygen/mbedtls.doxyfile
@@ -32,10 +32,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=""