Added documentation

Author: ItsMeSamey

src/backends/linux_browser_host.zig

@@ -6,6 +6,7 @@ pub const LaunchResult = struct {
     is_child_process: bool = true,
 };
 
+/// Launches a browser process and returns tracked process metadata when successful.
 pub fn launchTracked(
     allocator: std.mem.Allocator,
     browser_path: []const u8,
@@ -30,6 +31,7 @@ pub fn launchTracked(
     };
 }
 
+/// Opens a URL using an existing browser installation path.
 pub fn openUrlInExistingInstall(
     allocator: std.mem.Allocator,
     browser_path: []const u8,
@@ -39,13 +41,15 @@ pub fn openUrlInExistingInstall(
     return launched != null;
 }
 
+/// Terminates a tracked browser process on Linux.
 pub fn terminateProcess(_: std.mem.Allocator, pid_value: i64) void {
     if (pid_value <= 0) return;
     const pid: std.posix.pid_t = @intCast(pid_value);
     std.posix.kill(pid, std.posix.SIG.TERM) catch {};
     std.posix.kill(pid, std.posix.SIG.KILL) catch {};
 }
 
+/// Returns whether the tracked browser process is still alive.
 pub fn isProcessAlive(_: std.mem.Allocator, pid_value: i64) bool {
     if (pid_value <= 0) return false;
 
@@ -60,6 +64,7 @@ pub fn isProcessAlive(_: std.mem.Allocator, pid_value: i64) bool {
     return !isZombieProcessLinux(pid);
 }
 
+/// Applies a coarse native window control action to the launched browser process.
 pub fn controlWindow(allocator: std.mem.Allocator, pid: i64, cmd: window_style_types.WindowControl) bool {
     if (pid <= 0) return false;
 

src/backends/linux_webview/rounded_shape.zig

@@ -2,6 +2,7 @@ const std = @import("std");
 const common = @import("common.zig");
 const symbols_mod = @import("symbols.zig");
 
+/// Applies a rounded clip region to a GTK toplevel window when the runtime supports it.
 pub fn applyRoundedWindowShape(
     symbols: *const symbols_mod.Symbols,
     corner_radius: ?u16,

src/backends/linux_webview/symbols.zig

@@ -147,6 +147,7 @@ pub const Symbols = struct {
     cairo_fill: ?*const fn (*common.cairo_t) callconv(.c) void = null,
     cairo_region_destroy: ?*const fn (*common.cairo_region_t) callconv(.c) void = null,
 
+    /// \Uload for.
     pub fn loadFor(target: RuntimeTarget) !Symbols {
         var syms: Symbols = undefined;
         try syms.loadDynLibs(target);
@@ -155,6 +156,7 @@ pub const Symbols = struct {
         return syms;
     }
 
+    /// Releases resources owned by this value.
     pub fn deinit(self: *Symbols) void {
         _ = self;
         // Intentionally do not dlclose GTK/WebKit/GLib stacks at runtime.
@@ -165,6 +167,7 @@ pub const Symbols = struct {
         // Process-exit cleanup is sufficient for this host runtime.
     }
 
+    /// Returns init toolkit.
     pub fn initToolkit(self: *const Symbols) void {
         if (self.gtk_api == .gtk4) {
             if (self.gtk_init_gtk4) |init| {
@@ -175,13 +178,15 @@ pub const Symbols = struct {
         if (self.gtk_init_gtk3) |init| init(null, null);
     }
 
+    /// Returns new top level window.
     pub fn newTopLevelWindow(self: *const Symbols) ?*common.GtkWidget {
         return switch (self.gtk_api) {
             .gtk3 => if (self.gtk_window_new_gtk3) |create| create(common.GTK_WINDOW_TOPLEVEL) else null,
             .gtk4 => if (self.gtk_window_new_gtk4) |create| create() else null,
         };
     }
 
+    /// Returns add window child.
     pub fn addWindowChild(self: *const Symbols, window_widget: *common.GtkWidget, child_widget: *common.GtkWidget) ?*common.GtkWidget {
         switch (self.gtk_api) {
             .gtk3 => {
@@ -212,15 +217,18 @@ pub const Symbols = struct {
         }
     }
 
+    /// \Ushow window.
     pub fn showWindow(self: *const Symbols, window_widget: *common.GtkWidget, child_widget: *common.GtkWidget) void {
         self.gtk_widget_show(child_widget);
         self.gtk_widget_show(window_widget);
     }
 
+    /// \Uqueue widget draw.
     pub fn queueWidgetDraw(self: *const Symbols, widget: *common.GtkWidget) void {
         if (self.gtk_widget_queue_draw) |queue_draw| queue_draw(widget);
     }
 
+    /// \Udestroy window.
     pub fn destroyWindow(self: *const Symbols, window_widget: *common.GtkWidget) void {
         switch (self.gtk_api) {
             .gtk3 => {
@@ -241,14 +249,17 @@ pub const Symbols = struct {
         }
     }
 
+    /// \Uset window position center.
     pub fn setWindowPositionCenter(self: *const Symbols, window: *common.GtkWindow) void {
         if (self.gtk_window_set_position) |set_pos| set_pos(window, common.GTK_WIN_POS_CENTER);
     }
 
+    /// \Uset window position.
     pub fn setWindowPosition(self: *const Symbols, window: *common.GtkWindow, x: c_int, y: c_int) void {
         if (self.gtk_window_move) |move| move(window, x, y);
     }
 
+    /// \Uapply transparent visual.
     pub fn applyTransparentVisual(self: *const Symbols, window_widget: *common.GtkWidget) void {
         switch (self.gtk_api) {
             .gtk3 => {
@@ -269,6 +280,7 @@ pub const Symbols = struct {
         }
     }
 
+    /// \Uapply gtk4 window style.
     pub fn applyGtk4WindowStyle(
         self: *const Symbols,
         window_widget: *common.GtkWidget,
@@ -318,6 +330,7 @@ pub const Symbols = struct {
         }
     }
 
+    /// \Uminimize window.
     pub fn minimizeWindow(self: *const Symbols, window: *common.GtkWindow) void {
         if (self.gtk_window_iconify) |iconify| {
             iconify(window);
@@ -326,6 +339,7 @@ pub const Symbols = struct {
         if (self.gtk_window_minimize) |minimize| minimize(window);
     }
 
+    /// \Uset window min size.
     pub fn setWindowMinSize(self: *const Symbols, window_widget: *common.GtkWidget, min_size: ?common.Size) void {
         const set_size = self.gtk_widget_set_size_request orelse return;
         if (min_size) |size| {
@@ -335,6 +349,7 @@ pub const Symbols = struct {
         }
     }
 
+    /// \Uset window kiosk.
     pub fn setWindowKiosk(self: *const Symbols, window: *common.GtkWindow, enabled: bool) void {
         if (enabled) {
             if (self.gtk_window_fullscreen) |fullscreen| fullscreen(window);
@@ -343,6 +358,7 @@ pub const Symbols = struct {
         }
     }
 
+    /// \Uset window high contrast.
     pub fn setWindowHighContrast(
         self: *const Symbols,
         window_widget: *common.GtkWidget,
@@ -380,6 +396,7 @@ pub const Symbols = struct {
         }
     }
 
+    /// \Uset window icon from path.
     pub fn setWindowIconFromPath(self: *const Symbols, window_widget: *common.GtkWidget, path_z: [*:0]const u8) void {
         const window: *common.GtkWindow = @ptrCast(window_widget);
 
@@ -421,6 +438,7 @@ pub const Symbols = struct {
         set_icon_list(@ptrCast(surface), list);
     }
 
+    /// \Uclear window icon.
     pub fn clearWindowIcon(self: *const Symbols, window_widget: *common.GtkWidget) void {
         const window: *common.GtkWindow = @ptrCast(window_widget);
 
@@ -440,6 +458,7 @@ pub const Symbols = struct {
         set_icon_list(@ptrCast(surface), null);
     }
 
+    /// Returns whether the rounded shape.
     pub fn supportsRoundedShape(self: *const Symbols) bool {
         return self.gtk_widget_shape_combine_region != null and
             self.gtk_widget_input_shape_combine_region != null and
@@ -458,6 +477,7 @@ pub const Symbols = struct {
             self.cairo_region_destroy != null;
     }
 
+    /// \Uset rounded region.
     pub fn setRoundedRegion(self: *const Symbols, window_widget: *common.GtkWidget, region: ?*common.cairo_region_t) void {
         if (self.gtk_widget_shape_combine_region) |shape| shape(window_widget, region);
         if (self.gtk_widget_input_shape_combine_region) |input_shape| input_shape(window_widget, region);

src/backends/linux_webview_host.zig

@@ -53,6 +53,7 @@ pub const Host = struct {
     closed: std.atomic.Value(bool) = std.atomic.Value(bool).init(false),
     shutdown_requested: bool = false,
 
+    /// \Ustart.
     pub fn start(
         allocator: std.mem.Allocator,
         title: []const u8,
@@ -79,6 +80,7 @@ pub const Host = struct {
         return host;
     }
 
+    /// Releases resources owned by this value.
     pub fn deinit(self: *Host) void {
         _ = self.enqueue(.shutdown) catch {};
 
@@ -129,30 +131,36 @@ pub const Host = struct {
         self.allocator.destroy(self);
     }
 
+    /// Returns whether the ready.
     pub fn isReady(self: *Host) bool {
         self.mutex.lock();
         defer self.mutex.unlock();
         return self.ui_ready and !self.closed.load(.acquire);
     }
 
+    /// Returns whether the closed.
     pub fn isClosed(self: *Host) bool {
         return self.closed.load(.acquire);
     }
 
+    /// \Unavigate.
     pub fn navigate(self: *Host, url: []const u8) !void {
         const duped = try self.allocator.dupe(u8, url);
         errdefer self.allocator.free(duped);
         try self.enqueue(.{ .navigate = duped });
     }
 
+    /// \Uapply style.
     pub fn applyStyle(self: *Host, style: WindowStyle) !void {
         try self.enqueue(.{ .apply_style = style });
     }
 
+    /// \Ucontrol.
     pub fn control(self: *Host, cmd: WindowControl) !void {
         try self.enqueue(.{ .control = cmd });
     }
 
+    /// Returns pump.
     pub fn pump(self: *Host) void {
         drainCommandsUiThread(self);
 
@@ -237,6 +245,7 @@ fn initOnCurrentThread(host: *Host) !void {
     should_destroy_window = false;
 }
 
+/// Returns runtime available for.
 pub fn runtimeAvailableFor(target: RuntimeTarget) bool {
     const cache_ptr = switch (target) {
         .webview => &probe_cache_webview,

src/backends/macos_browser_host.zig

@@ -6,6 +6,7 @@ pub const LaunchResult = struct {
     is_child_process: bool = true,
 };
 
+/// Launches a browser process and returns tracked process metadata when successful.
 pub fn launchTracked(
     allocator: std.mem.Allocator,
     browser_path: []const u8,
@@ -27,6 +28,7 @@ pub fn launchTracked(
     return .{ .pid = @as(i64, @intCast(child.id)), .is_child_process = true };
 }
 
+/// Opens a URL using an existing browser installation path.
 pub fn openUrlInExistingInstall(
     allocator: std.mem.Allocator,
     browser_path: []const u8,
@@ -36,13 +38,15 @@ pub fn openUrlInExistingInstall(
     return launched != null;
 }
 
+/// Terminates a tracked browser process on macOS.
 pub fn terminateProcess(_: std.mem.Allocator, pid_value: i64) void {
     if (pid_value <= 0) return;
     const pid: std.posix.pid_t = @intCast(pid_value);
     std.posix.kill(pid, std.posix.SIG.TERM) catch {};
     std.posix.kill(pid, std.posix.SIG.KILL) catch {};
 }
 
+/// Returns whether the tracked browser process is still alive.
 pub fn isProcessAlive(_: std.mem.Allocator, pid_value: i64) bool {
     if (pid_value <= 0) return false;
 
@@ -56,6 +60,7 @@ pub fn isProcessAlive(_: std.mem.Allocator, pid_value: i64) bool {
     return true;
 }
 
+/// Applies a coarse native window control action to the launched browser process.
 pub fn controlWindow(allocator: std.mem.Allocator, pid: i64, cmd: window_style_types.WindowControl) bool {
     if (pid <= 0) return false;
 

src/backends/macos_webview/bindings.zig

@@ -18,6 +18,7 @@ pub const Symbols = struct {
     autorelease_pool_push: ObjcAutoreleasePoolPushFn,
     autorelease_pool_pop: ObjcAutoreleasePoolPopFn,
 
+    /// \Uload.
     pub fn load() !Symbols {
         var objc = try std.DynLib.open("/usr/lib/libobjc.A.dylib");
         errdefer objc.close();
@@ -46,6 +47,7 @@ pub const Symbols = struct {
         };
     }
 
+    /// Releases resources owned by this value.
     pub fn deinit(self: *Symbols) void {
         self.webkit.close();
         self.appkit.close();

src/backends/macos_webview_host.zig

@@ -79,6 +79,7 @@ pub const Host = struct {
 
     explicit_hidden: bool = false,
 
+    /// \Ustart.
     pub fn start(allocator: std.mem.Allocator, title: []const u8, style: WindowStyle) !*Host {
         if (!runtimeAvailable()) return error.NativeBackendUnavailable;
 
@@ -116,6 +117,7 @@ pub const Host = struct {
         return host;
     }
 
+    /// Releases resources owned by this value.
     pub fn deinit(self: *Host) void {
         self.enqueue(.shutdown) catch {};
 
@@ -134,26 +136,31 @@ pub const Host = struct {
         self.allocator.destroy(self);
     }
 
+    /// Returns whether the ready.
     pub fn isReady(self: *Host) bool {
         self.mutex.lock();
         defer self.mutex.unlock();
         return self.ui_ready and !self.closed.load(.acquire);
     }
 
+    /// Returns whether the closed.
     pub fn isClosed(self: *Host) bool {
         return self.closed.load(.acquire);
     }
 
+    /// \Unavigate.
     pub fn navigate(self: *Host, url: []const u8) !void {
         const duped = try self.allocator.dupe(u8, url);
         errdefer self.allocator.free(duped);
         try self.enqueue(.{ .navigate = duped });
     }
 
+    /// \Uapply style.
     pub fn applyStyle(self: *Host, style: WindowStyle) !void {
         try self.enqueue(.{ .apply_style = style });
     }
 
+    /// \Ucontrol.
     pub fn control(self: *Host, cmd: WindowControl) !void {
         try self.enqueue(.{ .control = cmd });
     }
@@ -173,6 +180,7 @@ pub const Host = struct {
     }
 };
 
+/// Returns runtime available.
 pub fn runtimeAvailable() bool {
     if (builtin.os.tag != .macos) return false;
     var symbols = objc.Symbols.load() catch return false;