Further documentation improvements
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
This commit is contained in:
parent
787f7c8d10
commit
4348a83bc8
1 changed files with 10 additions and 10 deletions
|
@ -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,
|
||||
# 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=""
|
||||
|
|
Loading…
Reference in a new issue