yuzu-emu/mbedtls
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity
mbedtls/doxygen/mbedtls.doxyfile

56 lines
2.2 KiB
Text
Raw Normal View History

Bump version ./scripts/bump_version.sh --version 3.5.1 Signed-off-by: Dave Rodgman <dave.rodgman@arm.com>
2024-01-22 16:45:49 +01:00
PROJECT_NAME = "Mbed TLS v3.5.2"
Have doxygen run in the doxygen directory When the Doxywizzard GUI is used and the doxyfile is loaded, the workind directory for doxygen is set to the location of the doxyfile. However the Make and CMake build systems expect doxygen to be ran from the top level directory. This commit unifies the build system and the Doxywizzard GUI so that all of them expect doxygen to be executed in the doxygen directory.
2018-01-19 16:21:11 +01:00
OUTPUT_DIRECTORY = ../apidoc/
- Added Doxygen source code documentation parts (donated by Fox-IT)
2011-01-06 13:28:03 +01:00
FULL_PATH_NAMES = NO
OPTIMIZE_OUTPUT_FOR_C = YES
EXTRACT_ALL = YES
EXTRACT_PRIVATE = YES
EXTRACT_STATIC = YES
CASE_SENSE_NAMES = NO
Allow context types with an ALT version to be linked in Doxygen In our tests, we run `tests/scripts/doxygen.sh`, which checks that `doxygen` runs without warnings after `scripts/config.py realfull`. In this configuration, alternative implementations such as `MBEDTLS_RSA_ALT` are enabled, which allows the documentation to contain references to the `MBEDTLS_xxx_ALT` symbol itself. However, this disables context types that alternative implementations must define in their header, such as `mbedtls_rsa_context`. See https://github.com/Mbed-TLS/mbedtls/issues/4518 As a partial fix, allow `tests/scripts/doxygen.sh` to see dummy definitions of the context type. This way, we can use both `#MBEDTLS_RSA_ALT` and `#mbedtls_rsa_context` cross-references in our documentation. This is not ideal, because `doxygen.sh` isn't testing for errors in the documentation of the affected context types, but it's cheap progress. Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
2024-01-23 17:45:33 +01:00
INPUT = ../include input ../tests/include/alt-dummy
Use only headers for doxygen (no doc in C files)
2015-03-10 18:37:30 +01:00
FILE_PATTERNS = *.h
- Added Doxygen source code documentation parts (donated by Fox-IT)
2011-01-06 13:28:03 +01:00
RECURSIVE = YES
Doxygen: don't traverse symbolic links We don't use symbolic links as part of our build process, so tell Doxygen not to traverse them. In particular, if I have a symbolic link to a directory outside the build tree, I don't want Doxygen to follow it.
2017-12-22 15:34:37 +01:00
EXCLUDE_SYMLINKS = YES
- Added Doxygen source code documentation parts (donated by Fox-IT)
2011-01-06 13:28:03 +01:00
SOURCE_BROWSER = YES
REFERENCED_BY_RELATION = YES
REFERENCES_RELATION = YES
ALPHABETICAL_INDEX = NO
HTML_OUTPUT = .
HTML_TIMESTAMP = YES
doxygen: enable the search engine Signed-off-by: Andrzej Kurek <andrzej.kurek@arm.com>
2022-01-21 14:43:44 +01:00
SEARCHENGINE = YES
- Added Doxygen source code documentation parts (donated by Fox-IT)
2011-01-06 13:28:03 +01:00
GENERATE_LATEX = NO
Improve positioning of GENERATE_XML option It is clearer to have this option next to the GENERATE_LATEX option. Signed-off-by: David Horstmann <david.horstmann@arm.com>
2023-03-22 18:35:14 +01:00
GENERATE_XML = YES
Adjust doxyfile to expand MBEDTLS_PRIVATE macro. Signed-off-by: Mateusz Starzyk <mateusz.starzyk@mobica.com>
2021-05-20 14:41:22 +02:00
MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = YES
Add an include path to the doxyfile to fix preprocessing for docs Previously, doxygen was unable to effectively use preprocessing to determine which parts of code should be documented. This was due to its inability to include headers during preprocessing, which was discovered by running it in preprocessing debug mode: doxygen -d preprocessor mbedtls.doxyfile An example of failure: "#include mbedtls/config.h: not found! skipping..." With the following fix includes are properly preprocessed with the documentation being considerably larger. Signed-off-by: Andrzej Kurek <andrzej.kurek@arm.com>
2020-03-27 17:58:13 +01:00
INCLUDE_PATH = ../include
Adjust doxyfile to expand MBEDTLS_PRIVATE macro. Signed-off-by: Mateusz Starzyk <mateusz.starzyk@mobica.com>
2021-05-20 14:41:22 +02:00
EXPAND_AS_DEFINED = MBEDTLS_PRIVATE
- Added Doxygen source code documentation parts (donated by Fox-IT)
2011-01-06 13:28:03 +01:00
CLASS_DIAGRAMS = NO
HAVE_DOT = YES
Upgraded doxygen config file
2013-09-10 16:17:15 +02:00
DOT_GRAPH_MAX_NODES = 200
- Added Doxygen source code documentation parts (donated by Fox-IT)
2011-01-06 13:28:03 +01:00
MAX_DOT_GRAPH_DEPTH = 1000
DOT_TRANSPARENT = YES
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 <Gilles.Peskine@arm.com>
2023-02-14 19:15:40 +01:00
Words. Use them! Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
2023-02-23 13:37:54 +01:00
# We mostly use \retval declarations to document which error codes a function
Further documentation improvements Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
2023-02-23 13:03:30 +01:00
# 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.
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 <Gilles.Peskine@arm.com>
2023-02-14 19:15:40 +01:00
# https://github.com/Mbed-TLS/mbedtls/issues/6960
# https://github.com/llvm/llvm-project/issues/60315
Further documentation improvements Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
2023-02-23 13:03:30 +01:00
# As a workaround, you can write something like
Improve documentation of documentation workaround Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
2023-02-21 10:21:12 +01:00
# \retval #PSA_ERROR_INSUFFICIENT_MEMORY \emptydescription
Further documentation improvements Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
2023-02-23 13:03:30 +01:00
# This avoids writing redundant text and keeps Clang happy.
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 <Gilles.Peskine@arm.com>
2023-02-14 19:15:40 +01:00
ALIASES += emptydescription=""
Tell Doxygen to generate XML Signed-off-by: David Horstmann <david.horstmann@arm.com>
2023-03-14 15:20:38 +01:00
Ignore mbedtls macros causing warnings Sphinx's breathe plugin cannot readily parse the Mbed TLS macros, so define the less essential ones away at the doxygen step to reduce the number of warnings. Signed-off-by: David Horstmann <david.horstmann@arm.com>
2023-03-16 17:07:12 +01:00
# Define away Mbed TLS macros that make parsing definitions difficult.
# MBEDTLS_DEPRECATED is not included in this list as it's important to
# display deprecated status in the documentation.
PREDEFINED = "MBEDTLS_CHECK_RETURN_CRITICAL=" \
"MBEDTLS_CHECK_RETURN_TYPICAL=" \
"MBEDTLS_CHECK_RETURN_OPTIONAL=" \
"MBEDTLS_PRINTF_ATTRIBUTE(a,b)=" \
Enable certain documented defines only when generating doxygen Avoid an "unrecognized define" error. Signed-off-by: Andrzej Kurek <andrzej.kurek@arm.com>
2023-07-03 12:52:37 +02:00
"__DOXYGEN__" \
Ignore mbedtls macros causing warnings Sphinx's breathe plugin cannot readily parse the Mbed TLS macros, so define the less essential ones away at the doxygen step to reduce the number of warnings. Signed-off-by: David Horstmann <david.horstmann@arm.com>
2023-03-16 17:07:12 +01:00
Reference in a new issue Copy permalink