Merge branch 'bugfix/doc_macro_definitions' into 'master'

doc: Fix macro definitions for different targets

See merge request espressif/esp-idf!8999

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);
 

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;  /*!<ADC unit index info. 0: ADC1; 1: ADC2.  */
         } type2;                    /*!<When the configured output format is 11bit. `ADC_DIGI_FORMAT_11BIT` */
-        uint16_t val;
+        uint16_t val;               /*!<Raw data value */
     };
 } adc_digi_output_data_t;
 
@@ -191,10 +191,10 @@ typedef struct {
                                          1: input voltage * 1/1.34;
                                          2: input voltage * 1/2;
                                          3: input voltage * 1/3.6. */
-            uint8_t reserved:  2;    /*!< reserved0 */
+            uint8_t reserved:  2;   /*!< reserved0 */
             uint8_t channel:   4;   /*!< ADC channel index. */
         };
-        uint8_t val;
+        uint8_t val;                /*!< Raw entry value */
     };
 } adc_digi_pattern_table_t;
 

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"
 

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

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'}

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):
@@ -57,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.