From 06ad0204f9e6c74f7e3ae06d89323d9bd022d5eb Mon Sep 17 00:00:00 2001
From: Tommaso Negri <me@tommasongr.com>
Date: Fri, 7 Aug 2026 23:51:15 +0200
Subject: improve documentation

---
 Sources/phbar/Config.swift | 52 ++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 46 insertions(+), 6 deletions(-)

(limited to 'Sources/phbar/Config.swift')

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
 		}
 	}
-- 
cgit v1.2.3