From 7d989e08fdbff6361c882d93eef0a6524695d731 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 543d18dd1..382d584ec 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 ef98aa841..1c82f50fa 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 ea9322937fb8fa98f3393ea7100dee2c22fea144 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 8effe6bc2..da5f325f1 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 a171def1ba8667943239746f4a363a46e0197a49 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 28fdea36a..dd9288a3c 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 1c82f50fa..7aaa89cd6 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 8193b188e8ed08f1a003bb1cbce80c3b3da371c2 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 ef7508738..f3f544a40 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 1305d276c..c066ea401 100644 --- a/components/soc/include/hal/adc_types.h +++ b/components/soc/include/hal/adc_types.h @@ -108,7 +108,7 @@ typedef struct { If (channel > ADC_CHANNEL_MAX), The data is invalid. */ uint16_t unit: 1; /*!