From db07c3edb45d2c6f2f1fc0fe5c421def8f2e1eb2 Mon Sep 17 00:00:00 2001 From: Victor Wheeler Date: Tue, 6 May 2025 08:07:57 -0600 Subject: [PATCH] docs: fix Doxygen parsing of attribute prefixes (#8179) --- docs/Doxyfile | 11 ++++++++++- docs/doxygen_xml.py | 34 +++++++++++++++++++++++++++++++++- src/display/lv_display.h | 4 ---- src/draw/sw/lv_draw_sw_mask.h | 4 ---- src/misc/lv_math.h | 7 ------- src/misc/lv_timer.h | 4 ---- src/others/monkey/lv_monkey.h | 8 +++----- 7 files changed, 46 insertions(+), 26 deletions(-) diff --git a/docs/Doxyfile b/docs/Doxyfile index 123a67158b..cbe999e09c 100644 --- a/docs/Doxyfile +++ b/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 diff --git a/docs/doxygen_xml.py b/docs/doxygen_xml.py index 1b3295ecba..9e40dfac1b 100644 --- a/docs/doxygen_xml.py +++ b/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) diff --git a/src/display/lv_display.h b/src/display/lv_display.h index 2f00b4f5b8..cded4bf4ad 100644 --- a/src/display/lv_display.h +++ b/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); /*--------------------- diff --git a/src/draw/sw/lv_draw_sw_mask.h b/src/draw/sw/lv_draw_sw_mask.h index 3f7b306e41..a70ce26354 100644 --- a/src/draw/sw/lv_draw_sw_mask.h +++ b/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` diff --git a/src/misc/lv_math.h b/src/misc/lv_math.h index ef226f4dfc..4395994fa9 100644 --- a/src/misc/lv_math.h +++ b/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 diff --git a/src/misc/lv_timer.h b/src/misc/lv_timer.h index be25003331..063b283ef9 100644 --- a/src/misc/lv_timer.h +++ b/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. diff --git a/src/others/monkey/lv_monkey.h b/src/others/monkey/lv_monkey.h index 97fc6e377c..f86f991b9e 100644 --- a/src/others/monkey/lv_monkey.h +++ b/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;