Further documentation improvements

Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>

doxygen/mbedtls.doxyfile

@@ -28,17 +28,17 @@ DOT_GRAPH_MAX_NODES    = 200
 MAX_DOT_GRAPH_DEPTH    = 1000
 DOT_TRANSPARENT        = YES
 
-# Doxygen accepts empty descriptions for commands such as \retval,
+# We mostly \retval declarations to document which error codes a function
-# but clang -Wdocumentation doesn't (since Clang 15, for \retval).
+# 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
+# As a workaround, you can write something like
-# 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
+# This avoids writing redundant text and keeps Clang happy.
-# it pacifies clang -Wdocumentation.
 ALIASES += emptydescription=""