From 787f7c8d10b43ce25f648de47a879c264bb2eb24 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Tue, 21 Feb 2023 10:21:12 +0100 Subject: [PATCH] Improve documentation of documentation workaround Signed-off-by: Gilles Peskine --- doxygen/mbedtls.doxyfile | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) 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=""