From 41797da955df466d99b8a91a4b7f481c4fa8e2b7 Mon Sep 17 00:00:00 2001 From: phranck Date: Fri, 30 Jan 2026 15:43:15 +0100 Subject: [PATCH] docs: Add missing doc comments to all public declarations (E.1) Add /// doc comments to 26 public declarations across 5 files: - StatusBar.swift: StatusBarItemOrder properties/init/operator, StatusBarItem 5 stored properties, StatusBarItemProtocol.matches(), StatusBarItemBuilder 6 result builder methods - Button.swift: ButtonRowBuilder 5 result builder methods - Appearance.swift: Appearance.ID rawValue and init - PaddingModifier.swift: Edge rawValue and init - Preferences.swift: NavigationTitleKey.defaultValue All public API is now fully documented for DocC generation. --- Sources/TUIKit/Core/Appearance.swift | 4 +++ Sources/TUIKit/Core/Preferences.swift | 1 + .../TUIKit/Modifiers/PaddingModifier.swift | 4 +++ Sources/TUIKit/Views/Button.swift | 5 ++++ Sources/TUIKit/Views/StatusBar.swift | 26 +++++++++++++++++++ 5 files changed, 40 insertions(+) diff --git a/Sources/TUIKit/Core/Appearance.swift b/Sources/TUIKit/Core/Appearance.swift index 139824b..28307bb 100644 --- a/Sources/TUIKit/Core/Appearance.swift +++ b/Sources/TUIKit/Core/Appearance.swift @@ -99,8 +99,12 @@ extension Appearance { /// } /// ``` public struct ID: RawRepresentable, Hashable, Sendable { + /// The string identifier for this appearance. public let rawValue: String + /// Creates an appearance ID from a raw string value. + /// + /// - Parameter rawValue: The string identifier. public init(rawValue: String) { self.rawValue = rawValue } diff --git a/Sources/TUIKit/Core/Preferences.swift b/Sources/TUIKit/Core/Preferences.swift index 29e6375..0615248 100644 --- a/Sources/TUIKit/Core/Preferences.swift +++ b/Sources/TUIKit/Core/Preferences.swift @@ -261,5 +261,6 @@ extension OnPreferenceChangeModifier: Renderable { /// A preference key for the navigation title. public struct NavigationTitleKey: PreferenceKey { + /// The default navigation title (empty string). public static let defaultValue: String = "" } diff --git a/Sources/TUIKit/Modifiers/PaddingModifier.swift b/Sources/TUIKit/Modifiers/PaddingModifier.swift index 82349d2..b0748c6 100644 --- a/Sources/TUIKit/Modifiers/PaddingModifier.swift +++ b/Sources/TUIKit/Modifiers/PaddingModifier.swift @@ -52,8 +52,12 @@ public struct EdgeInsets: Sendable, Equatable { /// The edges of a view. public struct Edge: OptionSet, Sendable { + /// The raw bitmask value for this edge set. public let rawValue: UInt8 + /// Creates an edge set from a raw bitmask value. + /// + /// - Parameter rawValue: The bitmask value. public init(rawValue: UInt8) { self.rawValue = rawValue } diff --git a/Sources/TUIKit/Views/Button.swift b/Sources/TUIKit/Views/Button.swift index d03c3f5..7e74161 100644 --- a/Sources/TUIKit/Views/Button.swift +++ b/Sources/TUIKit/Views/Button.swift @@ -406,22 +406,27 @@ public struct ButtonRow: View { /// Result builder for creating button rows. @resultBuilder public struct ButtonRowBuilder { + /// Combines multiple buttons into a single array. public static func buildBlock(_ buttons: Button...) -> [Button] { buttons } + /// Combines an array of button arrays (from `for` loops). public static func buildArray(_ components: [[Button]]) -> [Button] { components.flatMap { $0 } } + /// Handles optional button arrays (from `if` without `else`). public static func buildOptional(_ component: [Button]?) -> [Button] { component ?? [] } + /// Handles the first branch of an `if`/`else`. public static func buildEither(first component: [Button]) -> [Button] { component } + /// Handles the second branch of an `if`/`else`. public static func buildEither(second component: [Button]) -> [Button] { component } diff --git a/Sources/TUIKit/Views/StatusBar.swift b/Sources/TUIKit/Views/StatusBar.swift index 39d63aa..cb5fa70 100644 --- a/Sources/TUIKit/Views/StatusBar.swift +++ b/Sources/TUIKit/Views/StatusBar.swift @@ -262,12 +262,17 @@ public enum Shortcut { /// StatusBarItem(shortcut: "s", label: "save", order: .default) /// ``` public struct StatusBarItemOrder: Comparable, Sendable { + /// The numeric sort value (lower values appear first). public let value: Int + /// Creates a status bar item order with the given sort value. + /// + /// - Parameter value: The numeric sort value. public init(_ value: Int) { self.value = value } + /// Compares two orders by their numeric value. public static func < (lhs: Self, rhs: Self) -> Bool { lhs.value < rhs.value } @@ -333,6 +338,12 @@ extension StatusBarItemProtocol { /// Default order for user-defined items. public var order: StatusBarItemOrder { .default } + /// Whether this item's trigger key matches the given key event. + /// + /// Returns `false` if the item has no trigger key (informational only). + /// + /// - Parameter event: The key event to match against. + /// - Returns: `true` if the event matches this item's trigger key. public func matches(_ event: KeyEvent) -> Bool { guard let trigger = triggerKey else { return false } return event.key == trigger @@ -358,10 +369,19 @@ extension StatusBarItemProtocol { /// } /// ``` public struct StatusBarItem: StatusBarItemProtocol, Identifiable { + /// The unique identifier for this item. public let id: String + + /// The shortcut key(s) displayed to the user (e.g. `"q"`, `"↑↓"`). public let shortcut: String + + /// The descriptive label shown next to the shortcut (e.g. `"quit"`, `"nav"`). public let label: String + + /// The key that triggers this item's action, or `nil` for informational items. public let triggerKey: Key? + + /// The sort order controlling horizontal position in the status bar. public let order: StatusBarItemOrder /// The action to perform when the shortcut is triggered. @@ -571,26 +591,32 @@ public enum SystemStatusBarItem { /// Result builder for creating status bar items. @resultBuilder public struct StatusBarItemBuilder { + /// Combines multiple item arrays into a single flat array. public static func buildBlock(_ components: [any StatusBarItemProtocol]...) -> [any StatusBarItemProtocol] { components.flatMap { $0 } } + /// Combines an array of item arrays (from `for` loops). public static func buildArray(_ components: [[any StatusBarItemProtocol]]) -> [any StatusBarItemProtocol] { components.flatMap { $0 } } + /// Handles optional item arrays (from `if` without `else`). public static func buildOptional(_ component: [any StatusBarItemProtocol]?) -> [any StatusBarItemProtocol] { component ?? [] } + /// Handles the first branch of an `if`/`else`. public static func buildEither(first component: [any StatusBarItemProtocol]) -> [any StatusBarItemProtocol] { component } + /// Handles the second branch of an `if`/`else`. public static func buildEither(second component: [any StatusBarItemProtocol]) -> [any StatusBarItemProtocol] { component } + /// Wraps a single item into an array. public static func buildExpression(_ expression: any StatusBarItemProtocol) -> [any StatusBarItemProtocol] { [expression] }