more comments

Author: ItsMeSamey

examples/shared/demo_runner.zig

@@ -4,29 +4,51 @@ const time_compat = @import("time_compat");
 const env_compat = @import("env_compat");
 const webui = @import("webui");
 
+/// Enumerates example kind values.
 pub const ExampleKind = enum {
+    /// Selects `minimal`.
     minimal,
+    /// Selects `call_js_from_zig`.
     call_js_from_zig,
+    /// Selects `call_zig_from_js`.
     call_zig_from_js,
+    /// Selects `bidirectional_rpc`.
     bidirectional_rpc,
+    /// Selects `serve_folder`.
     serve_folder,
+    /// Selects `vfs`.
     vfs,
+    /// Selects `public_network`.
     public_network,
+    /// Selects `multi_client`.
     multi_client,
+    /// Selects `chatgpt_api`.
     chatgpt_api,
+    /// Selects `custom_web_server`.
     custom_web_server,
+    /// Selects `react`.
     react,
+    /// Selects `frameless`.
     frameless,
+    /// Selects `fancy_window`.
     fancy_window,
+    /// Selects `translucent_rounded`.
     translucent_rounded,
+    /// Selects `text_editor`.
     text_editor,
+    /// Selects `minimal_oop`.
     minimal_oop,
+    /// Selects `call_js_oop`.
     call_js_oop,
+    /// Selects `call_oop_from_js`.
     call_oop_from_js,
+    /// Selects `serve_folder_oop`.
     serve_folder_oop,
+    /// Selects `vfs_oop`.
     vfs_oop,
 };
 
+/// Stores rpc methods.
 pub const rpc_methods = struct {
     /// Returns a stable ping response used by the shared example frontend.
     pub fn ping() []const u8 {

src/backends/linux_browser_host.zig

@@ -4,8 +4,11 @@ const env_compat = @import("env_compat");
 const window_style_types = @import("../root/window_style.zig");
 const linux = std.os.linux;
 
+/// Captures launch result.
 pub const LaunchResult = struct {
+    /// Stores the pid.
     pid: i64,
+    /// Whether is child process.
     is_child_process: bool = true,
 };
 

src/backends/linux_webview/symbols.zig

@@ -38,30 +38,49 @@ const Command = union(enum) {
     }
 };
 
+/// Owns platform-native host state and thread-affine resources.
 pub const Host = struct {
+    /// Allocates host-owned buffers and runtime state.
     allocator: std.mem.Allocator,
+    /// Stores the current native window title.
     title: []u8,
+    /// Stores the last applied window style.
     style: WindowStyle,
+    /// Stores the runtime target.
     runtime_target: RuntimeTarget = .webview,
 
+    /// Stores the mutex.
     mutex: thread_compat.Mutex = .{},
+    /// Stores the queue.
     queue: Queue,
 
+    /// Stores the symbols.
     symbols: ?Symbols = null,
+    /// Stores the window widget.
     window_widget: ?*common.GtkWidget = null,
+    /// Stores the content widget.
     content_widget: ?*common.GtkWidget = null,
+    /// Stores the webview.
     webview: ?*common.WebKitWebView = null,
+    /// Stores the icon temp path.
     icon_temp_path: ?[]u8 = null,
 
+    /// Stores the ui ready.
     ui_ready: bool = false,
+    /// Stores the closed.
     closed: std.atomic.Value(bool) = std.atomic.Value(bool).init(false),
+    /// Stores the shutdown requested.
     shutdown_requested: bool = false,
 
     /// Start.
     pub fn start(
+        /// Allocates host-owned buffers and runtime state.
         allocator: std.mem.Allocator,
+        /// Stores the current native window title.
         title: []const u8,
+        /// Stores the last applied window style.
         style: WindowStyle,
+        /// Stores the runtime target.
         runtime_target: RuntimeTarget,
     ) !*Host {
         if (!linuxNativeToolkitSupported()) return error.NativeBackendUnavailable;

src/backends/linux_webview_host.zig

@@ -2,8 +2,11 @@ const std = @import("std");
 const env_compat = @import("env_compat");
 const window_style_types = @import("../root/window_style.zig");
 
+/// Captures launch result.
 pub const LaunchResult = struct {
+    /// Stores the pid.
     pid: i64,
+    /// Whether is child process.
     is_child_process: bool = true,
 };
 

src/backends/macos_browser_host.zig

@@ -7,15 +7,24 @@ pub const SelRegisterNameFn = *const fn ([*:0]const u8) callconv(.c) SEL;
 pub const ObjcAutoreleasePoolPushFn = *const fn () callconv(.c) ?*anyopaque;
 pub const ObjcAutoreleasePoolPopFn = *const fn (?*anyopaque) callconv(.c) void;
 
+/// Stores dynamically resolved native symbol bindings.
 pub const Symbols = struct {
+    /// Binds `objc` from the native runtime.
     objc: std.DynLib,
+    /// Binds `appkit` from the native runtime.
     appkit: std.DynLib,
+    /// Binds `webkit` from the native runtime.
     webkit: std.DynLib,
 
+    /// Binds `objc_get_class` from the native runtime.
     objc_get_class: ObjcGetClassFn,
+    /// Binds `sel_register_name` from the native runtime.
     sel_register_name: SelRegisterNameFn,
+    /// Binds `objc_msg_send` from the native runtime.
     objc_msg_send: *const anyopaque,
+    /// Binds `autorelease_pool_push` from the native runtime.
     autorelease_pool_push: ObjcAutoreleasePoolPushFn,
+    /// Binds `autorelease_pool_pop` from the native runtime.
     autorelease_pool_pop: ObjcAutoreleasePoolPopFn,
 
     /// Loads the platform symbols.

src/backends/macos_webview/bindings.zig

@@ -40,21 +40,35 @@ const NSRect = extern struct {
     size: NSSize,
 };
 
+/// Owns platform-native host state and thread-affine resources.
 pub const Host = struct {
+    /// Allocates host-owned buffers and runtime state.
     allocator: std.mem.Allocator,
+    /// Stores the current native window title.
     title: []u8,
+    /// Stores the last applied window style.
     style: WindowStyle,
+    /// Stores the ui ready.
     ui_ready: bool = false,
+    /// Stores the closed.
     closed: std.atomic.Value(bool) = std.atomic.Value(bool).init(false),
 
+    /// Stores the symbols.
     symbols: ?objc.Symbols = null,
 
+    /// Stores the ns app.
     ns_app: ?*anyopaque = null,
+    /// Stores the ns window.
     ns_window: ?*anyopaque = null,
+    /// Stores the wk webview.
     wk_webview: ?*anyopaque = null,
+    /// Stores the app icon image.
     app_icon_image: ?*anyopaque = null,
+    /// Stores the kiosk active.
     kiosk_active: bool = false,
+    /// Stores the explicit hidden.
     explicit_hidden: bool = false,
+    /// Stores the owner thread id.
     owner_thread_id: std.Thread.Id = undefined,
 
     /// Starts the native Cocoa/WKWebView host on the current thread.

src/backends/macos_webview_host.zig

@@ -2,8 +2,11 @@ const std = @import("std");
 const env_compat = @import("env_compat");
 const window_style_types = @import("../root/window_style.zig");
 
+/// Captures launch result.
 pub const LaunchResult = struct {
+    /// Stores the pid.
     pid: i64,
+    /// Whether is child process.
     is_child_process: bool = true,
 };
 
@@ -187,7 +190,7 @@ test "windows show window command mapping is stable" {
 }
 
 test "powershell browser launch script does not request hidden window style" {
-    const script = try buildPowershellLaunchScript(std.testing.allocator, "C:\\Browser\\browser.exe", &.{ "http://127.0.0.1:4020/" });
+    const script = try buildPowershellLaunchScript(std.testing.allocator, "C:\\Browser\\browser.exe", &.{"http://127.0.0.1:4020/"});
     defer std.testing.allocator.free(script);
     try std.testing.expect(std.mem.indexOf(u8, script, "-WindowStyle Hidden") == null);
     try std.testing.expect(std.mem.indexOf(u8, script, "Start-Process") != null);

src/backends/windows_browser_host.zig

@@ -255,8 +255,11 @@ extern "kernel32" fn LoadLibraryW(lpLibFileName: win.LPCWSTR) callconv(.winapi)
 extern "kernel32" fn FreeLibrary(hLibModule: win.HMODULE) callconv(.winapi) win.BOOL;
 extern "kernel32" fn GetProcAddress(hModule: win.HMODULE, lpProcName: [*:0]const u8) callconv(.winapi) ?*const anyopaque;
 
+/// Stores dynamically resolved native symbol bindings.
 pub const Symbols = struct {
+    /// Binds `loader` from the native runtime.
     loader: win.HMODULE,
+    /// Binds `create_environment` from the native runtime.
     create_environment: CreateCoreWebView2EnvironmentWithOptionsFn,
 
     /// Loads the platform symbols.

src/backends/windows_webview/bindings.zig

@@ -193,37 +193,63 @@ extern "user32" fn DestroyIcon(win.HICON) callconv(.winapi) win.BOOL;
 extern "gdi32" fn CreateRoundRectRgn(i32, i32, i32, i32, i32, i32) callconv(.winapi) ?*anyopaque;
 extern "gdi32" fn DeleteObject(?*anyopaque) callconv(.winapi) win.BOOL;
 
+/// Owns platform-native host state and thread-affine resources.
 pub const Host = struct {
+    /// Allocates host-owned buffers and runtime state.
     allocator: std.mem.Allocator,
+    /// Stores the current native window title.
     title: []u8,
+    /// Stores the last applied window style.
     style: WindowStyle,
 
+    /// Stores the mutex.
     mutex: thread_compat.Mutex = .{},
+    /// Stores the queue.
     queue: std.array_list.Managed(Command),
+    /// Stores the owner thread id.
     owner_thread_id: std.Thread.Id = undefined,
 
+    /// Stores the startup done.
     startup_done: bool = false,
+    /// Stores the startup error.
     startup_error: ?anyerror = null,
+    /// Stores the ui ready.
     ui_ready: bool = false,
+    /// Stores the closed.
     closed: std.atomic.Value(bool) = std.atomic.Value(bool).init(false),
+    /// Stores the shutdown requested.
     shutdown_requested: bool = false,
+    /// Stores the pending async callbacks.
     pending_async_callbacks: usize = 0,
 
+    /// Stores the instance.
     instance: ?win.HINSTANCE = null,
+    /// Stores the class registered.
     class_registered: bool = false,
+    /// Stores the hwnd.
     hwnd: ?win.HWND = null,
+    /// Stores the window icon.
     window_icon: ?win.HICON = null,
+    /// Stores the window destroy started.
     window_destroy_started: bool = false,
 
+    /// Stores the symbols.
     symbols: ?wv2.Symbols = null,
+    /// Stores the com initialized.
     com_initialized: bool = false,
 
+    /// Stores the environment.
     environment: ?*wv2.ICoreWebView2Environment = null,
+    /// Stores the controller.
     controller: ?*wv2.ICoreWebView2Controller = null,
+    /// Stores the webview.
     webview: ?*wv2.ICoreWebView2 = null,
+    /// Stores the title changed token.
     title_changed_token: wv2.EventRegistrationToken = .{ .value = 0 },
+    /// Stores the title handler attached.
     title_handler_attached: bool = false,
 
+    /// Stores the pending url.
     pending_url: ?[]u8 = null,
 
     /// Start.