From 2b270bccbf82c8e9fa1d31be6dd464b87b97cd24 Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Tue, 2 Jun 2020 10:16:41 +1000 Subject: [PATCH 1/4] doc: Fix passing of build macros to Doxygen Regression in fbb54184ef006ae6644d0b52878414ec0b2af652, the dictionary passed to generate_doxygen function was still the project_description structure. --- docs/conf_common.py | 6 +++++- docs/idf_extensions/run_doxygen.py | 24 +++--------------------- 2 files changed, 8 insertions(+), 22 deletions(-) diff --git a/docs/conf_common.py b/docs/conf_common.py index 543d18dd18..382d584ec8 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -58,6 +58,10 @@ extensions = ['breathe', 'extensions.toctree_filter', 'extensions.list_filter', + # Note: order is important here, events must + # be registered by one extension before they can be + # connected to another extension + 'idf_extensions.include_build_file', 'idf_extensions.link_roles', 'idf_extensions.build_system', @@ -65,11 +69,11 @@ extensions = ['breathe', 'idf_extensions.gen_toolchain_links', 'idf_extensions.gen_version_specific_includes', 'idf_extensions.kconfig_reference', + 'idf_extensions.gen_defines', 'idf_extensions.run_doxygen', 'idf_extensions.gen_idf_tools_links', 'idf_extensions.format_idf_target', 'idf_extensions.latex_builder', - 'idf_extensions.gen_defines', 'idf_extensions.exclude_docs', # from https://github.com/pfalcon/sphinx_selective_exclude diff --git a/docs/idf_extensions/run_doxygen.py b/docs/idf_extensions/run_doxygen.py index ef98aa841a..1c82f50fac 100644 --- a/docs/idf_extensions/run_doxygen.py +++ b/docs/idf_extensions/run_doxygen.py @@ -21,27 +21,9 @@ ALL_KINDS = [ def setup(app): - # The idf_build_system extension will emit this event once it - app.connect('idf-info', generate_doxygen) - - return {'parallel_read_safe': True, 'parallel_write_safe': True, 'version': '0.1'} - - -def _parse_defines(header_path, sdk_config_path): - defines = {} - # Note: we run C preprocessor here without any -I arguments (except "sdkconfig.h"), so assumption is - # that these headers are all self-contained and don't include any other headers - # not in the same directory - print("Reading macros from %s..." % (header_path)) - processed_output = subprocess.check_output(["xtensa-esp32-elf-gcc", "-I", sdk_config_path, - "-dM", "-E", header_path]).decode() - for line in processed_output.split("\n"): - line = line.strip() - m = re.search("#define ([^ ]+) ?(.*)", line) - if m and not m.group(1).startswith("_"): - defines[m.group(1)] = m.group(2) - - return defines + # The idf_build_system extension will emit this event once it has generated documentation macro definitions + app.connect('idf-defines-generated', generate_doxygen) + return {'parallel_read_safe': True, 'parallel_write_safe': True, 'version': '0.2'} def generate_doxygen(app, defines): From db5d659762bbdf6608b320434d161e87f2c78d58 Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Tue, 2 Jun 2020 10:44:18 +1000 Subject: [PATCH 2/4] docs: Log the full list of macros, remove code-style macros to prevent Doxygen errors --- docs/idf_extensions/gen_defines.py | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/docs/idf_extensions/gen_defines.py b/docs/idf_extensions/gen_defines.py index 8effe6bc25..da5f325f14 100644 --- a/docs/idf_extensions/gen_defines.py +++ b/docs/idf_extensions/gen_defines.py @@ -7,6 +7,7 @@ import glob import os +import pprint import subprocess import re @@ -32,6 +33,11 @@ def generate_defines(app, project_description): for soc_header in soc_headers: defines.update(get_defines(soc_header, sdk_config_path)) + # write a list of definitions to make debugging easier + with open(os.path.join(app.config.build_dir, "macro-definitions.txt"), "w") as f: + pprint.pprint(defines, f) + print("Saved macro list to %s" % f.name) + add_tags(app, defines) app.emit('idf-defines-generated', defines) @@ -48,8 +54,14 @@ def get_defines(header_path, sdk_config_path): for line in processed_output.split("\n"): line = line.strip() m = re.search("#define ([^ ]+) ?(.*)", line) - if m and not m.group(1).startswith("_"): - defines[m.group(1)] = m.group(2) + if m: + name = m.group(1) + value = m.group(2) + if name.startswith("_"): + continue # toolchain macro + if (" " in value) or ("=" in value): + value = "" # macros that expand to multiple tokens (ie function macros) cause doxygen errors, so just mark as 'defined' + defines[name] = value return defines @@ -69,4 +81,4 @@ def setup(app): app.connect('idf-info', generate_defines) app.add_event('idf-defines-generated') - return {'parallel_read_safe': True, 'parallel_write_safe': True, 'version': '0.1'} + return {'parallel_read_safe': True, 'parallel_write_safe': True, 'version': '0.2'} From e3664e297bb008d89085ac35ecc2c0ca08cf4940 Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Tue, 2 Jun 2020 11:01:20 +1000 Subject: [PATCH 3/4] docs: Redirect all of Doxygen stderr to the warnings log Some errors (for example the errors caused by macro values, as fixed in previous commit) get logged to stderr even if WARN_LOGFILE is set, but Doxygen succeeds. --- docs/Doxyfile | 3 --- docs/idf_extensions/run_doxygen.py | 12 ++++++++++-- 2 files changed, 10 insertions(+), 5 deletions(-) diff --git a/docs/Doxyfile b/docs/Doxyfile index 28fdea36a5..dd9288a3c7 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -341,7 +341,4 @@ GENERATE_RTF = NO ## Skip distracting progress messages ## QUIET = YES -## Log warnings in a file for further review -## -WARN_LOGFILE = "doxygen-warning-log.txt" diff --git a/docs/idf_extensions/run_doxygen.py b/docs/idf_extensions/run_doxygen.py index 1c82f50fac..7aaa89cd67 100644 --- a/docs/idf_extensions/run_doxygen.py +++ b/docs/idf_extensions/run_doxygen.py @@ -39,8 +39,16 @@ def generate_doxygen(app, defines): }) doxyfile = os.path.join(app.config.docs_root, "Doxyfile") print("Running doxygen with doxyfile {}".format(doxyfile)) - # note: run Doxygen in the build directory, so the xml & xml_in files end up in there - subprocess.check_call(["doxygen", doxyfile], env=doxy_env, cwd=build_dir) + + # It's possible to have doxygen log warnings to a file using WARN_LOGFILE directive, + # but in some cases it will still log an error to stderr and return success! + # + # So take all of stderr and redirect it to a logfile (will contain warnings and errors) + logfile = os.path.join(build_dir, "doxygen-warning-log.txt") + + with open(logfile, "w") as f: + # note: run Doxygen in the build directory, so the xml & xml_in files end up in there + subprocess.check_call(["doxygen", doxyfile], env=doxy_env, cwd=build_dir, stderr=f) # Doxygen has generated XML files in 'xml' directory. # Copy them to 'xml_in', only touching the files which have changed. From c44a433b8b19b4cdd34c6fa132b6f0ad6bbe6c18 Mon Sep 17 00:00:00 2001 From: Angus Gratton Date: Tue, 2 Jun 2020 11:02:49 +1000 Subject: [PATCH 4/4] driver: Fix some doxygen warnings --- components/driver/include/driver/uart.h | 1 - components/soc/include/hal/adc_types.h | 6 +++--- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/components/driver/include/driver/uart.h b/components/driver/include/driver/uart.h index ef7508738d..f3f544a40b 100644 --- a/components/driver/include/driver/uart.h +++ b/components/driver/include/driver/uart.h @@ -858,7 +858,6 @@ esp_err_t uart_set_loop_back(uart_port_t uart_num, bool loop_back_en); * @param always_rx_timeout_en Set to false enable the default behavior of timeout interrupt, * set it to true to always trigger timeout interrupt. * - * * @return None */ void uart_set_always_rx_timeout(uart_port_t uart_num, bool always_rx_timeout_en); diff --git a/components/soc/include/hal/adc_types.h b/components/soc/include/hal/adc_types.h index f40836ad44..6780435805 100644 --- a/components/soc/include/hal/adc_types.h +++ b/components/soc/include/hal/adc_types.h @@ -179,7 +179,7 @@ typedef struct { If (channel > ADC_CHANNEL_MAX), The data is invalid. */ uint16_t unit: 1; /*!