Further documentation improvements
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
diff --git a/doxygen/mbedtls.doxyfile b/doxygen/mbedtls.doxyfile
index 8804401..6a590b3 100644
--- a/doxygen/mbedtls.doxyfile
+++ b/doxygen/mbedtls.doxyfile
@@ -26,17 +26,17 @@
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).
+# We mostly \retval declarations to document which error codes a function
+# can return. The reader can follow the hyperlink to the definition of the
+# constant to get the generic documentation of that error code. If we don't
+# have anything to say about the specific error code for the specific
+# function, we can leave the description part of the \retval command blank.
+# This is perfectly valid as far as Doxygen is concerned. However, with
+# Clang >=15, the -Wdocumentation option emits a warning for empty
+# descriptions.
# https://github.com/Mbed-TLS/mbedtls/issues/6960
# https://github.com/llvm/llvm-project/issues/60315
-# 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
+# As a workaround, 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.
+# This avoids writing redundant text and keeps Clang happy.
ALIASES += emptydescription=""