improve documentation

3 files changed, 25 insertions, 11 deletions

diff --git a/Sources/phbar/Models/HEX.swift b/Sources/phbar/Models/HEX.swift
index fbbdf39..a262630 100644
--- a/Sources/phbar/Models/HEX.swift
+++ b/Sources/phbar/Models/HEX.swift
@@ -23,7 +23,7 @@ struct HEX {
 	/// Creates a hex color from the given code.
 	///
 	/// - Parameter code: A hex color code. Stored verbatim; see ``HEX`` for the
-	///   accepted formats.
+	///                   accepted formats.
 	init(code: String) {
 		self.code = code
 	}
@@ -40,8 +40,8 @@ extension SwiftUI.Color {
 	/// Supported formats (the leading `#` is optional): `#RGB`, `#RGBA`,
 	/// `#RRGGBB`, and `#RRGGBBAA`. Single-digit components are expanded by
 	/// repeating the digit. When present, the trailing digits encode alpha
-	/// (opacity); otherwise opacity defaults to `1`. Malformed input resolves to
-	/// opaque black.
+	/// (opacity); otherwise opacity defaults to `1`. Malformed input resolves
+	/// to opaque black.
 	///
 	/// - Parameter code: A hex color code.
 	static func hex(_ code: String) -> SwiftUI.Color {
@@ -93,9 +93,9 @@ extension SwiftUI.Color {
 extension SwiftUI.Color.Resolved {
 	/// The hex code for this resolved color.
 	///
-	/// Components are clamped to `0...1` and quantized to 8 bits. The result is a
-	/// 6-digit `#RRGGBB` code, or an 8-digit `#RRGGBBAA` code when the color is
-	/// not fully opaque.
+	/// Components are clamped to `0...1` and quantized to 8 bits.
+	/// The result is a 6-digit `#RRGGBB` code, or an 8-digit `#RRGGBBAA` code
+	/// when the color is not fully opaque.
 	var hex: HEX {
 		let r = Int((min(max(Double(red), 0), 1) * 255).rounded())
 		let g = Int((min(max(Double(green), 0), 1) * 255).rounded())
diff --git a/Sources/phbar/Models/Runner.swift b/Sources/phbar/Models/Runner.swift
index a98d34a..2466e26 100644
--- a/Sources/phbar/Models/Runner.swift
+++ b/Sources/phbar/Models/Runner.swift
@@ -1,6 +1,6 @@
 import Foundation
 
-/// Runs a shell command and returns its stdout as cells (one per line).
+/// Runs a shell command and returns its stdout as separate lines.
 ///
 /// Blocking — always call from a background context (e.g. `Task.detached`).
 enum Runner {
@@ -34,9 +34,9 @@ enum Runner {
 		return parse(String(data: data, encoding: .utf8) ?? "")
 	}
 
-	/// Split output into cells: one per line. A single trailing newline (from a
-	/// final `\n`) is dropped; blank lines elsewhere are kept so a script can
-	/// emit intentional gaps.
+	/// Split output into lines. A single trailing newline
+	/// (from a final `\n`) is dropped; blank lines elsewhere
+	/// are kept so a script can emit intentional gaps.
 	static func parse(_ text: String) -> [String] {
 		var lines = text.components(separatedBy: "\n")
 		if lines.last == "" { lines.removeLast() }
diff --git a/Sources/phbar/Models/Screen.swift b/Sources/phbar/Models/Screen.swift
index e4b968f..870d3b6 100644
--- a/Sources/phbar/Models/Screen.swift
+++ b/Sources/phbar/Models/Screen.swift
@@ -1,8 +1,22 @@
 import AppKit
 
-@MainActor
+/// Helpers for multi-screen geometry.
+///
+/// Maps a bar configuration (position, height) into concrete
+/// screen coordinates so the window can be placed correctly
+/// on each display.
 enum Screen {
 	/// Frame of the bar within a screen, in global display coordinates.
+	///
+	/// - Parameters:
+	///   - screen: The screen to calculate the bar frame for.
+	///   - position: Whether the bar sits at the top or bottom
+	///               of the screen.
+	///   - height: The bar height in points (see ``Config/height``).
+	///
+	/// - Returns: An ``NSRect`` in screen coordinates. The bar spans
+	///            the full width of the screen and is anchored at the top
+	///            or bottom edge.
 	static func barFrame(_ screen: NSScreen, position: Config.Position, height: CGFloat) -> NSRect {
 		switch position {
 		case .top: