Skip to content

Commit

Permalink
Define a workaround for empty \retval description
Browse files Browse the repository at this point in the history
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 <[email protected]>
  • Loading branch information
gilles-peskine-arm committed Feb 24, 2023
1 parent 4dcc08c commit 2fb14e9
Showing 1 changed file with 12 additions and 0 deletions.
12 changes: 12 additions & 0 deletions doxygen/mbedtls.doxyfile
Original file line number Diff line number Diff line change
Expand Up @@ -25,3 +25,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=""

0 comments on commit 2fb14e9

Please sign in to comment.