From 8ea7d85851819d342d23389325413d7d47ac4acc Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Tue, 14 Feb 2023 19:15:40 +0100 Subject: [PATCH] Define a workaround for empty \retval description Since Clang 15, `clang -Wdocumentation` warns about an empty description in a Doxygen `\retval` command: ``` include/psa/crypto.h:91:23: error: empty paragraph passed to '\retval' command [-Werror,-Wdocumentation] * \retval #PSA_SUCCESS ~~~~~~~~~~~~~~~~~~~^ ``` Ideally `\retval` directives should have a description that describes the precise meaning of the return value, but we commonly use an empty description when the return value is a status code and the status code's description is sufficient documentation. As a workaround, define a Doxygen command `\emptydescription` that we can use to make the description source code non-empty, without changing the appearance. Using the command will be done in a subsequent commit. Signed-off-by: Gilles Peskine --- doxygen/mbedtls.doxyfile | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/doxygen/mbedtls.doxyfile b/doxygen/mbedtls.doxyfile index 0c744daaa..7e8d19611 100644 --- a/doxygen/mbedtls.doxyfile +++ b/doxygen/mbedtls.doxyfile @@ -27,3 +27,15 @@ HAVE_DOT = YES DOT_GRAPH_MAX_NODES = 200 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). +# 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 +# This does not change the documentation generated by Doxygen, but +# it pacifies clang -Wdocumentation. +ALIASES += emptydescription=""