docs(misc): fix doc issues described in issue #8839 (#8857)

Co-authored-by: cubic-dev-ai[bot] <191113872+cubic-dev-ai[bot]@users.noreply.github.com>

docs/src/_static/css/custom.css

@@ -1110,11 +1110,17 @@ figure figcaption .caption-text {
   font-size: 0.8rem;
 }
 
+/* Whitespace below figures and images... */
 article figure,
 article img {
   margin-bottom: 2rem;
 }
 
+/* ...except when the image is part of a figure. */
+article figure img {
+  margin-bottom: 0;
+}
+
 /*-------------------------------------------------------------------------
  * Code Highlighting
  *-------------------------------------------------------------------------*/
@@ -1126,7 +1132,6 @@ body[data-theme="dark"] .highlight .p {
 /*-------------------------------------------------------------------------
  * Glossary
  *-------------------------------------------------------------------------*/
-
 .glossary {
   display: flex;
   flex-direction: column;

docs/src/conf.py

@@ -315,7 +315,7 @@ html_show_sphinx = False          # Default = True; adds "Created using Sphinx"
 
 # Link images that have been resized with a scale option (scale, width, or height)
 # to their original full-resolution image.  This will not overwrite any link given
-# by the target option on the the image directive, if present.
+# by the target option on the image directive, if present.
 #
 # Tip
 #

docs/src/details/common-widget-features/styles/style-properties.rst

@@ -1299,7 +1299,7 @@ Move start point of object (e.g. scale tick) radially
 clip_corner
 ~~~~~~~~~~~
 
-Enable to clip the overflowed content on the rounded corner. Can be `true` or `false`.
+Enable clipping of content that overflows rounded corners of parent Widget. Can be `true` or `false`.
 
 .. raw:: html
 

docs/src/details/integration/bindings/api_json.rst

@@ -249,7 +249,7 @@ this field.  The possible "json_type" values are:
   - ``"args"``: array of ``"arg"`` json types.  (See definition above.)
 
 
-- ``"stdlib_type"``:  C integral type (int, unsigned int, float, etc.)
+- ``"stdlib_type"``:  C type (name of type comes from one of the ``std*.h`` header files)
 
   Fields:
 

docs/src/details/integration/bindings/micropython.rst

@@ -52,8 +52,8 @@ Here are some advantages of using LVGL in MicroPython:
 
 - Develop GUI in Python, a very popular high level language. Use paradigms such as Object-Oriented Programming.
 - Usually, GUI development requires multiple iterations to get things right. With C, each iteration consists of
-  **``Change code`` > ``Build`` > ``Flash`` > ``Run``**. In MicroPython it's just
-  **``Change code`` > ``Run``** ! You can even run commands interactively using the
+  ``Change code`` > ``Build`` > ``Flash`` > ``Run``. In MicroPython it's just
+  ``Change code`` > ``Run``\ ! You can even run commands interactively using the
   `REPL <https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop>`__ (the interactive prompt)
 
 

docs/src/details/integration/chip_vendors/renesas/ra_family.rst

@@ -23,8 +23,8 @@ Run the Project
   README.md files in the applicable repositories for info. FSPs can be downloaded
   `here <https://www.renesas.com/us/en/software-tool/flexible-software-package-fsp>`__.
   Please notice from FSP version 6.0 and above, LVGL is now part of the middleware section
-  of components.  Therefore when cloning the the latest versions of the supported LVGL board
-  repositories, recursive updating of the the git submodules is no longer needed.
+  of components.  Therefore when cloning the latest versions of the supported LVGL board
+  repositories, recursive updating of the git submodules is no longer needed.
 
 - JLink is used for debugging, it can be downloaded `here
   <https://www.segger.com/downloads/jlink/>`__.

docs/src/details/integration/pc/uefi.rst

@@ -29,7 +29,7 @@ Configure UEFI driver
 
     #define LV_USE_UEFI  1
 
-- Enable the the memory core functions, which are wrappers around AllocatePool and FreePool (using memory of type *EfiBootServicesData*) if you do not wan't to use your own implementations
+- Enable the memory core functions, which are wrappers around AllocatePool and FreePool (using memory of type *EfiBootServicesData*) if you do not wan't to use your own implementations
 
 .. code-block:: c
 

docs/src/details/libs/libpng.rst

@@ -4,7 +4,7 @@
 libpng Decoder
 ==============
 
-**libpng** is an LVGL interface to the the official PNG reference library, which
+**libpng** is an LVGL interface to the official PNG reference library, which
 supports almost all PNG features, is extensible, and has been extensively tested for
 over 28 years.
 

docs/src/details/main-modules/animation.rst

@@ -359,8 +359,12 @@ Call :cpp:expr:`lv_anim_timeline_get_reverse(timeline)` function to get whether
 Animation Timeline is also played in reverse after its forward play completes.
 
 Call :cpp:expr:`lv_anim_timeline_delete(timeline)` function to delete the Animation Timeline.
-**Note**: If you need to delete a Widget during Animation, be sure to delete the
-Animation Timeline before deleting the Widget. Otherwise, the program may crash or behave abnormally.
+
+.. caution::
+
+    If you need to delete a Widget during Animation, be sure to delete the Animation
+    Timeline before deleting the Widget. Otherwise, the program may crash or behave
+    abnormally.
 
 If a base object is set with :cpp:expr:`lv_anim_timeline_set_base_object(timeline, obj)`,
 ``var`` in the added animations is assumed to be a widget name (or path) string.

docs/src/details/main-modules/draw/draw_descriptors.rst

@@ -315,7 +315,7 @@ The inner circle (focal point) can be set with:
 Conic Gradients
 ---------------
 
-The conic gradient is defined between the angles of a circle, and colors are mapped
+The conic gradient is defined between two angles within a circle, and colors are mapped
 to each angle.
 
 After initializing the stops with :cpp:func:`lv_grad_init_stops`, the conic gradient
@@ -495,7 +495,8 @@ for controlling text rendering:
 :letter_space:  Additional space between characters.
 :ofs_x:         Horizontal text offset.
 :ofs_y:         Vertical text offset.
-:sel_start:     Index of the first character for selection (not byte index).
+:sel_start:     Index of the first character for selection (character index, not byte
+                index, since some characters can be multi-byte characters).
                 ``LV_DRAW_LABEL_NO_TXT_SEL`` means no selection.
 :sel_end:       Index of the last character for selection.
 :sel_color:     Color of selected characters.
@@ -505,7 +506,7 @@ for controlling text rendering:
                 See :cpp:type:`lv_base_dir_t`.
 :decor:         Text decoration, e.g., underline. See :cpp:type:`lv_text_decor_t`.
 :flag:          Flags for text rendering. See :cpp:type:`lv_text_flag_t`.
-:text_length:   Number of characters to render (0 means render until `\0`).
+:text_length:   Number of characters to render (0 means render until `\\0`).
 :text_local:    Set to 1 to allocate a buffer and copy the text.
 :text_static:   Indicates ``text`` is constant and its pointer can be cached.
 :hint:          Pointer to externally stored data to speed up rendering.
@@ -574,8 +575,8 @@ these fields:
 :color:        Line color.
 :width:        Line thickness.
 :opa:          Line opacity (0--255).
-:dash_width:   Length of dashes (0 means no dashes).
-:dash_gap:     Length of gaps between dashes (0 means no dashes).
+:dash_width:   Length of dashes (0 means no dashes --- a continuous line).
+:dash_gap:     Length of gaps between dashes (0 means no gaps --- a continuous line).
 :round_start:  Rounds the line start.
 :round_end:    Rounds the line end.
 :raw_end:      Set to 1 to skip end calculations if they are unnecessary.

docs/src/details/main-modules/draw/draw_layers.rst

@@ -62,11 +62,58 @@ the widget as possible, but due to the nature of transformations no slicing is
 possible in this case.
 
 
-Clip Corner
------------
+Clip Corner Layers
+------------------
 
-The ``clip_corner`` style property also causes LVGL to create a 2 layers with radius
-height for the top and bottom parts of the Widget.
+The ``clip_corner`` style property causes the corners of the parent Widget to clip the
+corners of child Widgets whose corners would otherwise overflow a rounded corner of
+the parent.
+
+Example:
+
+.. code-block:: c
+
+    lv_obj_t * clipper_obj = lv_obj_create(lv_screen_active());
+    lv_obj_set_style_bg_color(clipper_obj, lv_palette_main(LV_PALETTE_GREY), 0);
+    lv_obj_center(clipper_obj);
+    lv_obj_set_style_pad_all(clipper_obj, 0, 0);
+    lv_obj_set_style_radius(clipper_obj, 40, 0);
+
+    lv_obj_t * clipped_obj = lv_obj_create(clipper_obj);
+    lv_obj_set_style_bg_color(clipped_obj, lv_palette_main(LV_PALETTE_RED), 0);
+    lv_obj_set_size(clipped_obj, 80, 80);
+
+.. figure:: /_static/images/clip_corner_1_problem_being_solved.png
+    :align: center
+    :alt: Without Clip Corner Style
+
+    Without Clip Corner Style
+
+You can see that the parent's corners do not clip the children. But if you add this
+line, it will:
+
+.. code-block:: c
+
+    lv_obj_set_style_clip_corner(clipper_obj, true, 0);
+
+.. figure:: /_static/images/clip_corner_2_result.png
+    :align: center
+    :alt: Result of Clip Corner Style
+
+    Result of Clip Corner Style
+
+There is a temporary RAM cost to doing this.  With ``LV_USE_LAYER_DEBUG`` on...
+
+.. figure:: /_static/images/clip_corner_3_layers_created.png
+    :align: center
+    :alt: Layers Created to Implement Clip Corner Style While Rendering
+
+    Layers Created to Implement Clip Corner Style While Rendering
+
+...you can see that in order to clip the children, two intermediate layer work areas
+have to be temporarily allocated, each having a height equal to the radius-style value
+currently held by the parent.  These layer work areas are returned to the heap once
+rendering is complete.
 
 
 
@@ -176,7 +223,7 @@ To save memory, LVGL can render certain types of layers in smaller chunks:
     chunk is set using :c:macro:`LV_DRAW_LAYER_SIMPLE_BUF_SIZE` in ``lv_conf.h``.
 
 2.  **Transform Layers**:
-    Transform Widgets cannot be rendered in chunks because transformations
+    Transformed Widgets cannot be rendered in chunks because transformations
     often affect pixels outside the given area. For such layers, LVGL allocates
     a buffer large enough to render the entire transformed area without limits.
 

docs/src/details/main-modules/image.rst

@@ -149,7 +149,7 @@ want:
 - RGB332 for 8-bit color depth
 - RGB565 for 16-bit color depth
 - RGB565 Swap for 16-bit color depth (two bytes are swapped)
-- RGB888 for 32-bit color depth
+- RGB888 for 24-bit color depth (8-bit channels without an alpha channel)
 
 
 Manually creating an image

docs/src/details/main-modules/indev.rst

@@ -181,7 +181,7 @@ Multi-touch gestures overview
 
 To recognize multi touch gestures, recognizers are used. The structure ``lv_indev_t`` contains
 an array of recognizers, one per gesture type. These recognizers are initialized internally by ``lv_indev_create`` by calling
-``lv_indev_gesture_init_recognizers`` after the indev device is created. The the recognizers can then be configured to
+``lv_indev_gesture_init_recognizers`` after the indev device is created. The recognizers can then be configured to
 modify the gestures thresholds. These thresholds are used to be able to recognize the gesture only after the threshold
 have been reached. They can be set-up like this:
 

docs/src/details/widgets/chart.rst

@@ -322,7 +322,7 @@ Zoom
 ----
 
 To zoom the chart all you need to do is wrap it in a parent container and set the
-chart's width and/or height to a larger value.  Doing this will cause the the chart
+chart's width and/or height to a larger value.  Doing this will cause the chart
 to be scrollable in its parent --- the parent container provides the scrollable "view
 window".
 

examples/scroll/lv_example_scroll_7.c

@@ -114,7 +114,7 @@ void lv_example_scroll_7(void)
     lv_obj_align(low_label, LV_ALIGN_BOTTOM_LEFT, 10, -10);
 
     load_item(obj, 3);
-    /* These counters hold the the highest/lowest number currently loaded. */
+    /* These counters hold the highest/lowest number currently loaded. */
     top_num = 3;
     bottom_num = 3;
 

scripts/style_api_gen.py

@@ -371,7 +371,7 @@ props = [
 
 {'name': 'CLIP_CORNER',
  'style_type': 'num',   'var_type': 'bool',  'default':0, 'inherited': 0, 'layout': 0, 'ext_draw': 0,
- 'dsc': "Enable to clip the overflowed content on the rounded corner. Can be `true` or `false`." },
+ 'dsc': "Enable clipping of content that overflows rounded corners of parent Widget. Can be `true` or `false`." },
 
 {'name': 'OPA',
  'style_type': 'num',   'var_type': 'lv_opa_t',  'default':'`LV_OPA_COVER`', 'inherited': 1, 'layout': 0, 'ext_draw': 0,

src/core/lv_obj_draw.h

@@ -37,7 +37,7 @@ typedef enum {
 
     /**Simple layer means that the layer can be rendered in chunks.
      * For example with opa_layered = 140 it's possible to render only 10 lines
-     * from the layer. When it's ready go the the next 10 lines.
+     * from the layer. When it's ready go to the next 10 lines.
      * It avoids large memory allocations for the layer buffer.
      * The buffer size for a chunk can be set by `LV_DRAW_LAYER_SIMPLE_BUF_SIZE` in lv_conf.h.*/
     LV_LAYER_TYPE_SIMPLE,

src/core/lv_refr.c

@@ -861,7 +861,7 @@ static void refr_area(const lv_area_t * area_p, int32_t y_offset)
     }
     else if(disp_refr->render_mode == LV_DISPLAY_RENDER_MODE_DIRECT ||
             disp_refr->render_mode == LV_DISPLAY_RENDER_MODE_FULL) {
-        /*In direct mode and full mode the the buffer area is always the whole screen, not considering rotation*/
+        /*In direct mode and full mode the buffer area is always the whole screen, not considering rotation*/
         layer->buf_area.x1 = 0;
         layer->buf_area.y1 = 0;
         if(lv_display_get_matrix_rotation(disp_refr)) {
@@ -879,7 +879,7 @@ static void refr_area(const lv_area_t * area_p, int32_t y_offset)
     uint32_t tile_cnt = 1;
     int32_t tile_h = lv_area_get_height(area_p);
     if(LV_COLOR_FORMAT_IS_INDEXED(layer->color_format) == false) {
-        /* Assume that the the buffer size (can be screen sized or smaller in case of partial mode)
+        /* Assume that the buffer size (can be screen sized or smaller in case of partial mode)
          * and max tile size are the optimal scenario. From this calculate the ideal tile size
          * and set the tile count and tile height accordingly.
          */

src/draw/lv_draw_rect.h

@@ -120,7 +120,7 @@ typedef struct {
     /**Radius, LV_RADIUS_CIRCLE for max. radius */
     int32_t radius;
 
-    /**Color of the the shadow */
+    /**Color of shadow */
     lv_color_t color;
 
     /**Width of the shadow. (radius of the blur)*/

src/drivers/wayland/lv_wl_shm.c

@@ -143,7 +143,7 @@ lv_result_t lv_wayland_shm_resize_window(shm_ctx_t * context, struct window * wi
         return LV_RESULT_INVALID;
     }
 
-    /* Moves the buffers to the the unused list of the group */
+    /* Moves the buffers to the unused list of the group */
     smm_release(body_buf1);
     smm_release(body_buf2);
 

src/misc/lv_anim_timeline.h

@@ -79,7 +79,7 @@ void lv_anim_timeline_pause(lv_anim_timeline_t * at);
 void lv_anim_timeline_set_reverse(lv_anim_timeline_t * at, bool reverse);
 
 /**
- * Set the time to wait before starting the the animation.
+ * Set the time to wait before starting the animation.
  * Applies only when playing from the very start, or reverse from the very end.
  * @param at        pointer to an animation timeline
  * @param delay     the delay time in milliseconds