From 28ec11e52b53a2ac02c3bcd44b00d655c84838ec Mon Sep 17 00:00:00 2001
From: Mitchell Hashimoto <m@mitchellh.com>
Date: Wed, 2 Oct 2024 10:51:57 -0700
Subject: [PATCH] docs updates

---
 macos/Sources/App/macOS/AppDelegate.swift | 14 +++++++++-----
 src/apprt/action.zig                      |  2 +-
 src/input/Binding.zig                     |  6 +++++-
 3 files changed, 15 insertions(+), 7 deletions(-)

diff --git a/macos/Sources/App/macOS/AppDelegate.swift b/macos/Sources/App/macOS/AppDelegate.swift
index c1f2615bf..e926e380b 100644
--- a/macos/Sources/App/macOS/AppDelegate.swift
+++ b/macos/Sources/App/macOS/AppDelegate.swift
@@ -86,7 +86,9 @@ class AppDelegate: NSObject,
         return ProcessInfo.processInfo.systemUptime - applicationLaunchTime
     }
 
-    /// Tracks whether the application is currently visible
+    /// Tracks whether the application is currently visible. This can be gamed, i.e. if a user manually
+    /// brings each window one by one to the front. But at worst its off by one set of toggles and this
+    /// makes our logic very easy.
     private var isVisible: Bool = true
 
     override init() {
@@ -572,14 +574,16 @@ class AppDelegate: NSObject,
 
     /// Toggles visibility of all Ghosty Terminal windows. When hidden, activates Ghostty as the frontmost application
     @IBAction func toggleVisibility(_ sender: Any) {
-        for controller in NSApp.windows.compactMap({ $0.windowController as? BaseTerminalController }) {
+        // We only care about terminal windows.
+        for window in NSApp.windows.filter({ $0.windowController is BaseTerminalController }) {
             if isVisible {
-                controller.window?.orderOut(nil)
+                window.orderOut(nil)
             } else {
-                controller.window?.makeKeyAndOrderFront(nil)
+                window.makeKeyAndOrderFront(nil)
             }
         }
-       
+
+        // After bringing them all to front we make sure our app is active too.
         if !isVisible {
             NSApp.activate(ignoringOtherApps: true)
         }
diff --git a/src/apprt/action.zig b/src/apprt/action.zig
index 07985fbd0..5c8ba6a01 100644
--- a/src/apprt/action.zig
+++ b/src/apprt/action.zig
@@ -96,7 +96,7 @@ pub const Action = union(Key) {
     /// Toggle the quick terminal in or out.
     toggle_quick_terminal,
 
-    /// Toggle the visiblity of all Ghostty terminal windows
+    /// Toggle the visibility of all Ghostty terminal windows.
     toggle_visibility,
 
     /// Jump to a specific tab. Must handle the scenario that the tab
diff --git a/src/input/Binding.zig b/src/input/Binding.zig
index e10ef3b1f..9f4ebd626 100644
--- a/src/input/Binding.zig
+++ b/src/input/Binding.zig
@@ -387,7 +387,11 @@ pub const Action = union(enum) {
     /// configuration file to customize its behavior.
     toggle_quick_terminal: void,
 
-    /// Toggle visibility of all windows
+    /// Show/hide all windows. If all windows become shown, we also ensure
+    /// Ghostty is focused.
+    ///
+    /// This currently only works on macOS. When hiding all windows, we do
+    /// not yield focus to the previous application.
     toggle_visibility: void,
 
     /// Quit ghostty.