docs: fix Doxygen parsing of attribute prefixes (#8179)

docs/Doxyfile

@@ -2060,7 +2060,16 @@ INCLUDE_FILE_PATTERNS  =
 # recursively expanded use the := operator instead of the = operator.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-PREDEFINED             = DOXYGEN LV_CONF_PATH="../../lv_conf.h"
+PREDEFINED             = DOXYGEN                         \
+                         LV_CONF_PATH="../../lv_conf.h"  \
+                         LV_ATTRIBUTE_TICK_INC=          \
+                         LV_ATTRIBUTE_TIMER_HANDLER=     \
+                         LV_ATTRIBUTE_FLUSH_READY=       \
+                         LV_ATTRIBUTE_MEM_ALIGN=         \
+                         LV_ATTRIBUTE_LARGE_CONST=       \
+                         LV_ATTRIBUTE_LARGE_RAM_ARRAY=   \
+                         LV_ATTRIBUTE_FAST_MEM=          \
+                         LV_ATTRIBUTE_EXTERN_DATA=
 
 # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this
 # tag can be used to specify a list of macro names that should be expanded. The

docs/doxygen_xml.py

@@ -1562,7 +1562,6 @@ class DoxygenXml(object):
         cfg.set('XML_OUTPUT', "xml")
         cfg.set('HTML_OUTPUT', 'doxygen_html')
         cfg.set('INPUT', lvgl_src_dir)
-        cfg.set('PREDEFINED', f'DOXYGEN LV_CONF_PATH="{lv_conf_file}"')
         cfg.set('QUIET', 'YES')
         cfg.set('GENERATE_HTML', 'NO')
         cfg.set('GENERATE_DOCSET', 'NO')
@@ -1577,6 +1576,39 @@ class DoxygenXml(object):
         cfg.set('GENERATE_DOCBOOK', 'NO')
         cfg.set('GENERATE_PERLMOD', 'NO')
 
+        # The predefined definitions are:
+        # - DOXYGEN (defines it as 1 and allows conditional directives [e.g. #if]
+        #   to do special things when DOXYGEN is processing it, as opposed to
+        #   a C compiler.
+        # - LV_CONF_PATH predefines the path where `lv_conf_internal.h` will
+        #   include the `lv_conf.h` file.
+        # - All the others here are used when macros prefix a line of code like this:
+        #
+        #       LV_ATTRIBUTE_EXTERN_DATA extern const lv_obj_class_t lv_obj_class;
+        #
+        #   which occurs in `lv_obj.h`.  When these are added to the PREDEFINED list as
+        #   "MACRO_NAME=" with no value, Doxygen expands the macro to an empty string
+        #   allowing Doxygen to correctly parse the line.  The additional macros that
+        #   are treated that way are found in the middle of `lv_conf_template.h` in a
+        #   section called "COMPILER SETTINGS" with no definitions, made for prefixing
+        #   various code.  (This works around Doxygen's failure to correctly deal with
+        #   macros that are defined with no values, as these are in lv_conf.h.)
+        #   This list is current as of 28-Apr-2025.
+        predefined_symbols = [
+            'DOXYGEN',
+            f'LV_CONF_PATH="{lv_conf_file}"',
+            'LV_ATTRIBUTE_TICK_INC=',
+            'LV_ATTRIBUTE_TIMER_HANDLER=',
+            'LV_ATTRIBUTE_FLUSH_READY=',
+            'LV_ATTRIBUTE_MEM_ALIGN=',
+            'LV_ATTRIBUTE_LARGE_CONST=',
+            'LV_ATTRIBUTE_LARGE_RAM_ARRAY=',
+            'LV_ATTRIBUTE_FAST_MEM=',
+            'LV_ATTRIBUTE_EXTERN_DATA=',
+        ]
+
+        cfg.set('PREDEFINED', predefined_symbols)
+
         # Include TAGFILES if requested.
         if doxy_tagfile:
             cfg.set('GENERATE_TAGFILE', doxy_tagfile)

src/display/lv_display.h

@@ -364,8 +364,6 @@ void lv_display_set_antialiasing(lv_display_t * disp, bool en);
  */
 bool lv_display_get_antialiasing(lv_display_t * disp);
 
-//! @cond Doxygen_Suppress
-
 /**
  * Call from the display driver when the flushing is finished
  * @param disp      pointer to display whose `flush_cb` was called
@@ -381,8 +379,6 @@ LV_ATTRIBUTE_FLUSH_READY void lv_display_flush_ready(lv_display_t * disp);
  */
 LV_ATTRIBUTE_FLUSH_READY bool lv_display_flush_is_last(lv_display_t * disp);
 
-//! @endcond
-
 bool lv_display_is_double_buffered(lv_display_t * disp);
 
 /*---------------------

src/draw/sw/lv_draw_sw_mask.h

@@ -72,8 +72,6 @@ void lv_draw_sw_mask_init(void);
 
 void lv_draw_sw_mask_deinit(void);
 
-//! @cond Doxygen_Suppress
-
 /**
  * Apply the added buffers on a line. Used internally by the library's drawing routines.
  * @param masks the masks list to apply, must be ended with NULL pointer in array.
@@ -91,8 +89,6 @@ lv_draw_sw_mask_res_t /* LV_ATTRIBUTE_FAST_MEM */ lv_draw_sw_mask_apply(void * m
                                                                         int32_t abs_y,
                                                                         int32_t len);
 
-//! @endcond
-
 /**
  * Free the data from the parameter.
  * It's called inside `lv_draw_sw_mask_remove_id` and `lv_draw_sw_mask_remove_custom`

src/misc/lv_math.h

@@ -45,7 +45,6 @@ typedef struct {
  * GLOBAL PROTOTYPES
  **********************/
 
-//! @cond Doxygen_Suppress
 /**
  * Return with sinus of an angle
  * @param angle
@@ -55,8 +54,6 @@ int32_t /* LV_ATTRIBUTE_FAST_MEM */ lv_trigo_sin(int16_t angle);
 
 int32_t LV_ATTRIBUTE_FAST_MEM lv_trigo_cos(int16_t angle);
 
-//! @endcond
-
 /**
  * Calculate the y value of cubic-bezier(x1, y1, x2, y2) function as specified x.
  * @param x time in range of [0..LV_BEZIER_VAL_MAX]
@@ -88,8 +85,6 @@ int32_t lv_bezier3(int32_t t, int32_t u0, uint32_t u1, int32_t u2, int32_t u3);
  */
 uint16_t lv_atan2(int x, int y);
 
-//! @cond Doxygen_Suppress
-
 /**
  * Get the square root of a number
  * @param x integer which square root should be calculated
@@ -102,8 +97,6 @@ uint16_t lv_atan2(int x, int y);
  */
 void /* LV_ATTRIBUTE_FAST_MEM */ lv_sqrt(uint32_t x, lv_sqrt_res_t * q, uint32_t mask);
 
-//! @endcond
-
 /**
  * Alternative (fast, approximate) implementation for getting the square root of an integer.
  * @param x integer which square root should be calculated

src/misc/lv_timer.h

@@ -44,16 +44,12 @@ typedef void (*lv_timer_handler_resume_cb_t)(void * data);
  * GLOBAL PROTOTYPES
  **********************/
 
-//! @cond Doxygen_Suppress
-
 /**
  * Call it periodically to handle lv_timers.
  * @return time till it needs to be run next (in ms)
  */
 LV_ATTRIBUTE_TIMER_HANDLER uint32_t lv_timer_handler(void);
 
-//! @endcond
-
 /**
  * Call it in the super-loop of main() or threads. It will run lv_timer_handler()
  * with a given period in ms. You can use it with sleep or delay in OS environment.

src/others/monkey/lv_monkey.h

@@ -28,18 +28,16 @@ extern "C" {
 typedef struct _lv_monkey_t lv_monkey_t;
 
 struct _lv_monkey_config_t {
-    /**< Input device type*/
+    /** Input device type */
     lv_indev_type_t type;
 
-    /**< Monkey execution period*/
+    /** Monkey execution period */
     struct {
-        //! @cond Doxygen_Suppress
         uint32_t min;
         uint32_t max;
-        //! @endcond
     } period_range;
 
-    /**< The range of input value*/
+    /** The range of input value */
     struct {
         int32_t min;
         int32_t max;