improve documentation

4 files changed, 71 insertions, 17 deletions

diff --git a/Sources/phbar/Config.swift b/Sources/phbar/Config.swift
index 8015f4d..746aa7e 100644
--- a/Sources/phbar/Config.swift
+++ b/Sources/phbar/Config.swift
@@ -1,25 +1,49 @@
 import SwiftUI
 
+/// The top-level configuration for the bar.
+///
+/// Set appearance, define blocks, and choose the bar position here.
+/// This is the primary file a user edits to customise phbar.
 enum Config {
-	// Geometry
+	/// The bar height in points (pt).
+	///
+	/// Tip: Set this value to 30 to match the default macOS
+	/// menu bar height.
 	static let height: CGFloat = 30
+
+	/// The bar position on the screen.
 	static let position: Position = .top
 
-	// Appearance
+	/// The font used for all text and icons in the bar.
 	static let font: Font = .custom("Comic Code", fixedSize: 14)
+
+	/// The color used for texts and icons.
 	static let foreground: Color = .hex("#aed3f3")
+
+	/// The color used for the bar background.
 	static let background: Color = .hex("#010408").opacity(0.825)
 
-	// Blocks
+	/// The color used to highlight a cell inside a block (see ``Cell``).
+	static let highlight: Color = .hex("#0f304a")
+
+	/// The blocks that make up the bar, listed in display order.
+	///
+	/// Each block is positioned on the left or right side of the bar
+	/// and runs a shell command, optionally on a repeating interval.
+	/// See ``Config-swift.enum/Block`` for the full configuration options.
 	static let blocks: [Block] = [
-		Block(name: "app",   placement: .left,  command: "echo ' 􀙅 Safari '"),
-		Block(name: "clock", placement: .right, command: "echo ' TODAY '"),
+		Block(name: "app", placement: .left, command: "echo ' 􀙅 Safari '"),
+		Block(
+			name: "memory", placement: .right, command: "~/.config/phbar/scripts/memory", interval: 10),
+		Block(
+			name: "clock", placement: .right, command: "~/.config/phbar/scripts/clock", interval: 1),
 	]
 }
 
 // MARK: Support types
 
 extension Config {
+	/// The bar position on the screen.
 	enum Position: Sendable {
 		/// Anchor the bar at the top of the screen.
 		case top
@@ -28,6 +52,11 @@ extension Config {
 		case bottom
 	}
 
+	/// A block defined in the configuration.
+	///
+	/// Represents one unit of the bar. Each block is a named command that
+	/// produces output on an optional timer. See ``phbar/Block`` for the
+	/// runtime counterpart that manages execution and cell publishing.
 	struct Block: Sendable {
 		/// The block identifier used for manual updates.
 		///
@@ -46,6 +75,7 @@ extension Config {
 		/// to be re-evaluated.
 		let name: String
 
+		/// Whether the block anchors to the left or right side of the bar.
 		let placement: Placement
 
 		/// The shell command used for updating the content.
@@ -68,6 +98,14 @@ extension Config {
 		/// a notification later on.
 		let interval: Double?
 
+		/// Define a block of the bar.
+		///
+		/// - Parameters:
+		///   - name: The block identifier used for manual updates.
+		///   - placement: Left or right side of the bar.
+		///   - command: The shell command used for updating the content.
+		///   - interval: The interval, in seconds, at which the command is executed.
+		///
 		init(name: String, placement: Placement, command: String, interval: Double? = nil) {
 			self.name = name
 			self.placement = placement
@@ -75,9 +113,11 @@ extension Config {
 			self.interval = interval
 		}
 
+		/// Where the block is anchored inside the bar.
 		enum Placement: Sendable {
+			/// Anchored to the left side of the bar.
 			case left
-			case center
+			/// Anchored to the right side of the bar.
 			case right
 		}
 	}
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: