From 856bb89022fb9f70f21ede858429b2c4471f8d2c Mon Sep 17 00:00:00 2001 From: Virgil Date: Thu, 2 Apr 2026 19:12:40 +0000 Subject: [PATCH] docs(gui): align public API comments with AX --- pkg/display/display.go | 34 ++++++++++++++++++++++++++++++++++ pkg/display/events.go | 14 ++++++++------ pkg/webview/messages.go | 1 + pkg/window/messages.go | 1 + pkg/window/service.go | 2 ++ pkg/window/window.go | 5 ++++- 6 files changed, 50 insertions(+), 7 deletions(-) diff --git a/pkg/display/display.go b/pkg/display/display.go index 0966c2c..eb33e94 100644 --- a/pkg/display/display.go +++ b/pkg/display/display.go @@ -49,6 +49,7 @@ type Service struct { } // New is the constructor for the display service. +// Use: svc, err := display.New() func New() (*Service, error) { return &Service{ configData: map[string]map[string]any{ @@ -60,6 +61,7 @@ func New() (*Service, error) { } // Register creates a factory closure that captures the Wails app. +// Use: core.WithService(display.Register(app)) // Pass nil for testing without a Wails runtime. func Register(wailsApp *application.App) func(*core.Core) (any, error) { return func(c *core.Core) (any, error) { @@ -1060,12 +1062,14 @@ func (s *Service) windowService() *window.Service { // --- Window Management (delegates via IPC) --- // OpenWindow creates a new window via IPC. +// Use: _ = svc.OpenWindow(window.WithName("editor"), window.WithURL("/editor")) func (s *Service) OpenWindow(opts ...window.WindowOption) error { _, _, err := s.Core().PERFORM(window.TaskOpenWindow{Opts: opts}) return err } // GetWindowInfo returns information about a window via IPC. +// Use: info, err := svc.GetWindowInfo("editor") func (s *Service) GetWindowInfo(name string) (*window.WindowInfo, error) { result, handled, err := s.Core().QUERY(window.QueryWindowByName{Name: name}) if err != nil { @@ -1079,6 +1083,7 @@ func (s *Service) GetWindowInfo(name string) (*window.WindowInfo, error) { } // ListWindowInfos returns information about all tracked windows via IPC. +// Use: infos := svc.ListWindowInfos() func (s *Service) ListWindowInfos() []window.WindowInfo { result, handled, _ := s.Core().QUERY(window.QueryWindowList{}) if !handled { @@ -1089,18 +1094,21 @@ func (s *Service) ListWindowInfos() []window.WindowInfo { } // SetWindowPosition moves a window via IPC. +// Use: _ = svc.SetWindowPosition("editor", 160, 120) func (s *Service) SetWindowPosition(name string, x, y int) error { _, _, err := s.Core().PERFORM(window.TaskSetPosition{Name: name, X: x, Y: y}) return err } // SetWindowSize resizes a window via IPC. +// Use: _ = svc.SetWindowSize("editor", 1280, 800) func (s *Service) SetWindowSize(name string, width, height int) error { _, _, err := s.Core().PERFORM(window.TaskSetSize{Name: name, W: width, H: height}) return err } // SetWindowBounds sets both position and size of a window via IPC. +// Use: _ = svc.SetWindowBounds("editor", 160, 120, 1280, 800) func (s *Service) SetWindowBounds(name string, x, y, width, height int) error { if _, _, err := s.Core().PERFORM(window.TaskSetPosition{Name: name, X: x, Y: y}); err != nil { return err @@ -1110,65 +1118,76 @@ func (s *Service) SetWindowBounds(name string, x, y, width, height int) error { } // MaximizeWindow maximizes a window via IPC. +// Use: _ = svc.MaximizeWindow("editor") func (s *Service) MaximizeWindow(name string) error { _, _, err := s.Core().PERFORM(window.TaskMaximise{Name: name}) return err } // MinimizeWindow minimizes a window via IPC. +// Use: _ = svc.MinimizeWindow("editor") func (s *Service) MinimizeWindow(name string) error { _, _, err := s.Core().PERFORM(window.TaskMinimise{Name: name}) return err } // FocusWindow brings a window to the front via IPC. +// Use: _ = svc.FocusWindow("editor") func (s *Service) FocusWindow(name string) error { _, _, err := s.Core().PERFORM(window.TaskFocus{Name: name}) return err } // FocusSet is a compatibility alias for FocusWindow. +// Use: _ = svc.FocusSet("editor") func (s *Service) FocusSet(name string) error { return s.FocusWindow(name) } // CloseWindow closes a window via IPC. +// Use: _ = svc.CloseWindow("editor") func (s *Service) CloseWindow(name string) error { _, _, err := s.Core().PERFORM(window.TaskCloseWindow{Name: name}) return err } // RestoreWindow restores a maximized/minimized window via IPC. +// Use: _ = svc.RestoreWindow("editor") func (s *Service) RestoreWindow(name string) error { _, _, err := s.Core().PERFORM(window.TaskRestore{Name: name}) return err } // SetWindowVisibility shows or hides a window via IPC. +// Use: _ = svc.SetWindowVisibility("editor", false) func (s *Service) SetWindowVisibility(name string, visible bool) error { _, _, err := s.Core().PERFORM(window.TaskSetVisibility{Name: name, Visible: visible}) return err } // SetWindowAlwaysOnTop sets whether a window stays on top via IPC. +// Use: _ = svc.SetWindowAlwaysOnTop("editor", true) func (s *Service) SetWindowAlwaysOnTop(name string, alwaysOnTop bool) error { _, _, err := s.Core().PERFORM(window.TaskSetAlwaysOnTop{Name: name, AlwaysOnTop: alwaysOnTop}) return err } // SetWindowTitle changes a window's title via IPC. +// Use: _ = svc.SetWindowTitle("editor", "Core Editor") func (s *Service) SetWindowTitle(name string, title string) error { _, _, err := s.Core().PERFORM(window.TaskSetTitle{Name: name, Title: title}) return err } // SetWindowFullscreen sets a window to fullscreen mode via IPC. +// Use: _ = svc.SetWindowFullscreen("editor", true) func (s *Service) SetWindowFullscreen(name string, fullscreen bool) error { _, _, err := s.Core().PERFORM(window.TaskFullscreen{Name: name, Fullscreen: fullscreen}) return err } // SetWindowBackgroundColour sets the background colour of a window via IPC. +// Use: _ = svc.SetWindowBackgroundColour("editor", 0, 0, 0, 0) func (s *Service) SetWindowBackgroundColour(name string, r, g, b, a uint8) error { _, _, err := s.Core().PERFORM(window.TaskSetBackgroundColour{ Name: name, @@ -1181,6 +1200,7 @@ func (s *Service) SetWindowBackgroundColour(name string, r, g, b, a uint8) error } // SetWindowOpacity updates a window's opacity via IPC. +// Use: _ = svc.SetWindowOpacity("editor", 0.85) func (s *Service) SetWindowOpacity(name string, opacity float32) error { _, _, err := s.Core().PERFORM(window.TaskSetOpacity{ Name: name, @@ -1196,6 +1216,7 @@ func (s *Service) ClearWebviewConsole(name string) error { } // GetFocusedWindow returns the name of the currently focused window. +// Use: focused := svc.GetFocusedWindow() func (s *Service) GetFocusedWindow() string { infos := s.ListWindowInfos() for _, info := range infos { @@ -1207,6 +1228,7 @@ func (s *Service) GetFocusedWindow() string { } // GetWindowTitle returns the title of a window by name. +// Use: title, err := svc.GetWindowTitle("editor") func (s *Service) GetWindowTitle(name string) (string, error) { info, err := s.GetWindowInfo(name) if err != nil { @@ -1256,6 +1278,7 @@ type CreateWindowOptions struct { } // CreateWindow creates a new window with the specified options. +// Use: info, err := svc.CreateWindow(display.CreateWindowOptions{Name: "editor", URL: "/editor"}) func (s *Service) CreateWindow(opts CreateWindowOptions) (*window.WindowInfo, error) { if opts.Name == "" { return nil, fmt.Errorf("window name is required") @@ -1283,6 +1306,7 @@ func (s *Service) CreateWindow(opts CreateWindowOptions) (*window.WindowInfo, er // --- Layout delegation --- // SaveLayout saves the current window arrangement as a named layout. +// Use: _ = svc.SaveLayout("coding") func (s *Service) SaveLayout(name string) error { ws := s.windowService() if ws == nil { @@ -1300,6 +1324,7 @@ func (s *Service) SaveLayout(name string) error { } // RestoreLayout applies a saved layout. +// Use: _ = svc.RestoreLayout("coding") func (s *Service) RestoreLayout(name string) error { ws := s.windowService() if ws == nil { @@ -1324,6 +1349,7 @@ func (s *Service) RestoreLayout(name string) error { } // ListLayouts returns all saved layout names with metadata. +// Use: layouts := svc.ListLayouts() func (s *Service) ListLayouts() []window.LayoutInfo { ws := s.windowService() if ws == nil { @@ -1333,6 +1359,7 @@ func (s *Service) ListLayouts() []window.LayoutInfo { } // DeleteLayout removes a saved layout by name. +// Use: _ = svc.DeleteLayout("coding") func (s *Service) DeleteLayout(name string) error { ws := s.windowService() if ws == nil { @@ -1343,6 +1370,7 @@ func (s *Service) DeleteLayout(name string) error { } // GetLayout returns a specific layout by name. +// Use: layout := svc.GetLayout("coding") func (s *Service) GetLayout(name string) *window.Layout { ws := s.windowService() if ws == nil { @@ -1358,6 +1386,7 @@ func (s *Service) GetLayout(name string) *window.Layout { // --- Tiling/snapping delegation --- // TileWindows arranges windows in a tiled layout. +// Use: _ = svc.TileWindows(window.TileModeLeftRight, []string{"left", "right"}) func (s *Service) TileWindows(mode window.TileMode, windowNames []string) error { ws := s.windowService() if ws == nil { @@ -1368,6 +1397,7 @@ func (s *Service) TileWindows(mode window.TileMode, windowNames []string) error } // SnapWindow snaps a window to a screen edge or corner. +// Use: _ = svc.SnapWindow("editor", window.SnapRight) func (s *Service) SnapWindow(name string, position window.SnapPosition) error { ws := s.windowService() if ws == nil { @@ -1405,6 +1435,7 @@ func (s *Service) primaryScreenSize() (int, int) { } // StackWindows arranges windows in a cascade pattern. +// Use: _ = svc.StackWindows([]string{"editor", "terminal"}, 24, 24) func (s *Service) StackWindows(windowNames []string, offsetX, offsetY int) error { ws := s.windowService() if ws == nil { @@ -1414,6 +1445,7 @@ func (s *Service) StackWindows(windowNames []string, offsetX, offsetY int) error } // ApplyWorkflowLayout applies a predefined layout for a specific workflow. +// Use: _ = svc.ApplyWorkflowLayout(window.WorkflowCoding) func (s *Service) ApplyWorkflowLayout(workflow window.WorkflowLayout) error { ws := s.windowService() if ws == nil { @@ -1424,6 +1456,7 @@ func (s *Service) ApplyWorkflowLayout(workflow window.WorkflowLayout) error { } // ArrangeWindowPair places two windows side by side using the window manager's balanced split. +// Use: _ = svc.ArrangeWindowPair("editor", "terminal") func (s *Service) ArrangeWindowPair(first, second string) error { ws := s.windowService() if ws == nil { @@ -1434,6 +1467,7 @@ func (s *Service) ArrangeWindowPair(first, second string) error { } // FindSpace returns a free placement suggestion for a new window. +// Use: space, err := svc.FindSpace(800, 600) func (s *Service) FindSpace(width, height int) (window.SpaceInfo, error) { ws := s.windowService() if ws == nil { diff --git a/pkg/display/events.go b/pkg/display/events.go index 823872f..cee4a31 100644 --- a/pkg/display/events.go +++ b/pkg/display/events.go @@ -1,3 +1,4 @@ +// pkg/display/events.go package display import ( @@ -15,12 +16,12 @@ import ( type EventType string const ( - EventWindowFocus EventType = "window.focus" - EventWindowBlur EventType = "window.blur" - EventWindowMove EventType = "window.move" - EventWindowResize EventType = "window.resize" - EventWindowClose EventType = "window.close" - EventWindowCreate EventType = "window.create" + EventWindowFocus EventType = "window.focus" + EventWindowBlur EventType = "window.blur" + EventWindowMove EventType = "window.move" + EventWindowResize EventType = "window.resize" + EventWindowClose EventType = "window.close" + EventWindowCreate EventType = "window.create" EventThemeChange EventType = "theme.change" EventScreenChange EventType = "screen.change" EventNotificationClick EventType = "notification.click" @@ -72,6 +73,7 @@ type clientState struct { } // NewWSEventManager creates a new event manager. +// Use: events := display.NewWSEventManager() func NewWSEventManager() *WSEventManager { em := &WSEventManager{ upgrader: websocket.Upgrader{ diff --git a/pkg/webview/messages.go b/pkg/webview/messages.go index 55950bc..6de9a80 100644 --- a/pkg/webview/messages.go +++ b/pkg/webview/messages.go @@ -1,4 +1,5 @@ // pkg/webview/messages.go +// pkg/webview/messages.go package webview import "time" diff --git a/pkg/window/messages.go b/pkg/window/messages.go index fc91a8f..7ea8526 100644 --- a/pkg/window/messages.go +++ b/pkg/window/messages.go @@ -1,3 +1,4 @@ +// pkg/window/messages.go package window // WindowInfo contains information about a window. diff --git a/pkg/window/service.go b/pkg/window/service.go index e8ae9e4..bd3077f 100644 --- a/pkg/window/service.go +++ b/pkg/window/service.go @@ -1,3 +1,4 @@ +// pkg/window/service.go package window import ( @@ -13,6 +14,7 @@ import ( type Options struct{} // Service is a core.Service managing window lifecycle via IPC. +// Use: core.WithService(window.Register(window.NewMockPlatform())) // It embeds ServiceRuntime for Core access and composes Manager for platform operations. type Service struct { *core.ServiceRuntime[Options] diff --git a/pkg/window/window.go b/pkg/window/window.go index cfdb0db..e3c7631 100644 --- a/pkg/window/window.go +++ b/pkg/window/window.go @@ -49,6 +49,7 @@ type Manager struct { } // NewManager creates a window Manager with the given platform backend. +// Use: mgr := window.NewManager(platform) func NewManager(platform Platform) *Manager { return &Manager{ platform: platform, @@ -59,7 +60,7 @@ func NewManager(platform Platform) *Manager { } // NewManagerWithDir creates a window Manager with a custom config directory for state/layout persistence. -// Useful for testing or when the default config directory is not appropriate. +// Use: mgr := window.NewManagerWithDir(platform, t.TempDir()) func NewManagerWithDir(platform Platform, configDir string) *Manager { return &Manager{ platform: platform, @@ -84,6 +85,7 @@ func (m *Manager) SetDefaultHeight(height int) { } // Open creates a window using functional options, applies saved state, and tracks it. +// Use: _, err := mgr.Open(window.WithName("editor"), window.WithURL("/editor")) func (m *Manager) Open(opts ...WindowOption) (PlatformWindow, error) { w, err := ApplyOptions(opts...) if err != nil { @@ -93,6 +95,7 @@ func (m *Manager) Open(opts ...WindowOption) (PlatformWindow, error) { } // Create creates a window from a Window descriptor. +// Use: _, err := mgr.Create(&window.Window{Name: "editor", URL: "/editor"}) func (m *Manager) Create(w *Window) (PlatformWindow, error) { if w.Name == "" { w.Name = "main"