8ea7d85851
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 <Gilles.Peskine@arm.com>
41 lines
1.5 KiB
Text
41 lines
1.5 KiB
Text
PROJECT_NAME = "mbed TLS v3.3.0"
|
|
OUTPUT_DIRECTORY = ../apidoc/
|
|
FULL_PATH_NAMES = NO
|
|
OPTIMIZE_OUTPUT_FOR_C = YES
|
|
EXTRACT_ALL = YES
|
|
EXTRACT_PRIVATE = YES
|
|
EXTRACT_STATIC = YES
|
|
CASE_SENSE_NAMES = NO
|
|
INPUT = ../include input
|
|
FILE_PATTERNS = *.h
|
|
RECURSIVE = YES
|
|
EXCLUDE_SYMLINKS = YES
|
|
SOURCE_BROWSER = YES
|
|
REFERENCED_BY_RELATION = YES
|
|
REFERENCES_RELATION = YES
|
|
ALPHABETICAL_INDEX = NO
|
|
HTML_OUTPUT = .
|
|
HTML_TIMESTAMP = YES
|
|
SEARCHENGINE = YES
|
|
GENERATE_LATEX = NO
|
|
MACRO_EXPANSION = YES
|
|
EXPAND_ONLY_PREDEF = YES
|
|
INCLUDE_PATH = ../include
|
|
EXPAND_AS_DEFINED = MBEDTLS_PRIVATE
|
|
CLASS_DIAGRAMS = NO
|
|
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=""
|