Refine documentation for public API

This standardizes structure and enum documentation by replacing header
block descriptions with inline /**< */ comments.

Author: jserv

apps/clock.c

@@ -63,30 +63,23 @@ static void apps_clock_hand(twin_custom_widget_t *clock,
                             twin_argb32_t out_pixel)
 {
     twin_path_t *stroke = twin_path_create();
-    twin_path_t *pen = twin_path_create();
-    twin_path_t *path = twin_path_create();
-    twin_matrix_t m;
 
     apps_clock_set_transform(clock, stroke);
 
     twin_path_rotate(stroke, angle);
     twin_path_move(stroke, D(0), D(0));
     twin_path_draw(stroke, len, D(0));
 
-    m = twin_path_current_matrix(stroke);
-    m.m[2][0] = 0;
-    m.m[2][1] = 0;
-    twin_path_set_matrix(pen, m);
-    twin_path_set_matrix(path, m);
-    twin_path_circle(pen, 0, 0, fill_width);
-    twin_path_convolve(path, stroke, pen);
-
-    twin_paint_path(_apps_clock_pixmap(clock), fill_pixel, path);
+    /* Draw the filled part of the hand */
+    if (fill_width > 0)
+        twin_paint_stroke(_apps_clock_pixmap(clock), fill_pixel, stroke,
+                          fill_width * 2);
 
-    twin_paint_stroke(_apps_clock_pixmap(clock), out_pixel, path, out_width);
+    /* Draw the outline if needed */
+    if (out_width > 0 && out_pixel != fill_pixel)
+        twin_paint_stroke(_apps_clock_pixmap(clock), out_pixel, stroke,
+                          (fill_width + out_width) * 2);
 
-    twin_path_destroy(path);
-    twin_path_destroy(pen);
     twin_path_destroy(stroke);
 }
 

apps/multi.c

@@ -65,7 +65,7 @@ static void apps_circletext_start(twin_screen_t *screen,
         twin_path_utf8(path, "Hello, world!");
         twin_path_restore(path, &state);
     }
-    twin_fill_path(alpha, path, 0, 0);
+    twin_paint_path(alpha, 0xff000000, path);
     twin_path_destroy(path);
     twin_path_destroy(pen);
     source.source_kind = TWIN_SOLID;
@@ -112,7 +112,7 @@ static void apps_quickbrown_start(twin_screen_t *screen,
         fy += D(s);
     }
 
-    twin_fill_path(alpha, path, 0, 0);
+    twin_paint_path(alpha, 0xff000000, path);
     twin_path_destroy(path);
     twin_path_destroy(pen);
     source.source_kind = TWIN_SOLID;
@@ -160,7 +160,7 @@ static void apps_ascii_start(twin_screen_t *screen, int x, int y, int w, int h)
         fy += D(s + 2);
     }
 
-    twin_fill_path(alpha, path, 0, 0);
+    twin_paint_path(alpha, 0xff000000, path);
     twin_path_destroy(path);
     twin_path_destroy(pen);
     source.source_kind = TWIN_SOLID;
@@ -285,15 +285,15 @@ static void apps_blur(twin_screen_t *screen, int x, int y, int w, int h)
     twin_window_t *window = twin_window_create(
         screen, TWIN_ARGB32, TwinWindowApplication, x, y, w, h);
     twin_window_set_name(window, "Blur");
-    twin_pixmap_t *scaled_background = twin_pixmap_create(
-        TWIN_ARGB32, window->pixmap->width, window->pixmap->height);
+    int client_width = window->client.right - window->client.left;
+    int client_height = window->client.bottom - window->client.top;
+    twin_pixmap_t *scaled_background =
+        twin_pixmap_create(TWIN_ARGB32, client_width, client_height);
     twin_fixed_t sx, sy;
-    sx = twin_fixed_div(
-        twin_int_to_fixed(raw_background->width),
-        twin_int_to_fixed(window->client.right - window->client.left));
-    sy = twin_fixed_div(
-        twin_int_to_fixed(raw_background->height),
-        twin_int_to_fixed(window->client.bottom - window->client.top));
+    sx = twin_fixed_div(twin_int_to_fixed(raw_background->width),
+                        twin_int_to_fixed(client_width));
+    sy = twin_fixed_div(twin_int_to_fixed(raw_background->height),
+                        twin_int_to_fixed(client_height));
 
     twin_matrix_scale(&raw_background->transform, sx, sy);
     twin_operand_t srcop = {
@@ -304,18 +304,15 @@ static void apps_blur(twin_screen_t *screen, int x, int y, int w, int h)
     twin_composite(scaled_background, 0, 0, &srcop, 0, 0, 0, 0, 0, TWIN_SOURCE,
                    scaled_background->width, scaled_background->height);
 
-    twin_pointer_t src, dst;
-    for (int y = window->client.top; y < window->client.bottom; y++)
-        for (int x = window->client.left; x < window->client.right; x++) {
-            src =
-                twin_pixmap_pointer(scaled_background, x - window->client.left,
-                                    y - window->client.top);
-            dst = twin_pixmap_pointer(window->pixmap, x, y);
-            *dst.argb32 = *src.argb32 | 0xff000000;
-        }
-    twin_stack_blur(window->pixmap, 5, window->client.left,
-                    window->client.right, window->client.top,
-                    window->client.bottom);
+    /* Apply blur effect to the scaled background */
+    twin_stack_blur(scaled_background, 16, 0, scaled_background->width - 1, 0,
+                    scaled_background->height - 1);
+
+    /* Copy the blurred background to the window */
+    srcop.u.pixmap = scaled_background;
+    twin_composite(window->pixmap, window->client.left, window->client.top,
+                   &srcop, 0, 0, NULL, 0, 0, TWIN_SOURCE, client_width,
+                   client_height);
 
     twin_pixmap_destroy(scaled_background);
     twin_pixmap_destroy(raw_background);

apps/spline.c

@@ -143,7 +143,7 @@ static twin_dispatch_result_t _apps_spline_update_pos(
     spline->points[spline->which].y =
         twin_matrix_transform_y(&(spline->inverse_transition), x, y);
     twin_custom_widget_queue_paint(custom);
-    twin_widget_children_paint(twin_custom_widget_base(custom)->parent);
+    /* Parent will be repainted automatically */
     return TwinDispatchDone;
 }