From ff54e516cd53833a5cf3480481401f2f1197103d Mon Sep 17 00:00:00 2001 From: phranck Date: Sat, 7 Feb 2026 13:37:18 +0100 Subject: [PATCH] Docs: Add comprehensive documentation for result builders - Expand Scene protocol docs with overview, conformance guide, topics - Add SceneBuilder docs with usage example and explanation - Add ButtonRowBuilder docs with control flow support details - Add RadioButtonGroupBuilder docs with usage example - Add StatusBarItemBuilder docs with See Also references All result builders now have consistent, DocC-compatible documentation explaining their purpose, usage patterns, and supported control flow. --- Sources/TUIkit/App/Scene.swift | 65 ++++++++++++++++++-- Sources/TUIkit/StatusBar/StatusBarItem.swift | 35 ++++++++++- Sources/TUIkit/Views/ButtonRow.swift | 29 ++++++++- Sources/TUIkit/Views/RadioButton.swift | 30 ++++++++- 4 files changed, 151 insertions(+), 8 deletions(-) diff --git a/Sources/TUIkit/App/Scene.swift b/Sources/TUIkit/App/Scene.swift index cd43ca3..27e9f11 100644 --- a/Sources/TUIkit/App/Scene.swift +++ b/Sources/TUIkit/App/Scene.swift @@ -4,10 +4,41 @@ // Created by LAYERED.work // License: MIT -/// The base protocol for scenes in TUIkit. +/// The base protocol for scenes in TUIKit. /// -/// A scene represents a part of the app structure, -/// typically a window or a group of views. +/// A scene represents a distinct region of the app's user interface, +/// analogous to SwiftUI's `Scene` protocol. In TUIKit, scenes define +/// the top-level structure of your terminal application. +/// +/// ## Overview +/// +/// Scenes sit between the ``App`` and ``View`` layers in TUIKit's +/// architecture. While views define the content, scenes define how +/// that content is organized at the application level. +/// +/// Currently, TUIKit provides one scene type: +/// - ``WindowGroup``: Displays content in the terminal window +/// +/// ## Conforming to Scene +/// +/// You typically don't create custom scene types. Instead, use the +/// built-in ``WindowGroup`` in your app's `body`: +/// +/// ```swift +/// @main +/// struct MyApp: App { +/// var body: some Scene { +/// WindowGroup { +/// ContentView() +/// } +/// } +/// } +/// ``` +/// +/// ## Topics +/// +/// ### Built-in Scenes +/// - ``WindowGroup`` @MainActor public protocol Scene {} @@ -38,11 +69,35 @@ public struct WindowGroup: Scene { // MARK: - SceneBuilder -/// A result builder for scene hierarchies. +/// A result builder that constructs scene hierarchies from closures. +/// +/// `SceneBuilder` enables the declarative syntax used in ``App/body-swift.property`` +/// to define your application's scene structure. You don't use this type directly; +/// instead, the `@SceneBuilder` attribute is applied to the `body` property of +/// your ``App`` conforming type. +/// +/// ## Overview +/// +/// When you write: +/// +/// ```swift +/// var body: some Scene { +/// WindowGroup { +/// ContentView() +/// } +/// } +/// ``` +/// +/// The `@SceneBuilder` attribute transforms this closure into a scene that +/// TUIKit can render. Currently, `SceneBuilder` supports a single scene +/// in the body, which is typically a ``WindowGroup``. @MainActor @resultBuilder public struct SceneBuilder { - /// Builds a single scene. + /// Builds a scene expression from a single scene component. + /// + /// - Parameter content: The scene to build. + /// - Returns: The same scene, unchanged. public static func buildBlock(_ content: Content) -> Content { content } diff --git a/Sources/TUIkit/StatusBar/StatusBarItem.swift b/Sources/TUIkit/StatusBar/StatusBarItem.swift index 32958e2..c54fc20 100644 --- a/Sources/TUIkit/StatusBar/StatusBarItem.swift +++ b/Sources/TUIkit/StatusBar/StatusBarItem.swift @@ -604,7 +604,40 @@ public extension SystemStatusBarItem { // MARK: - Status Bar Item Builder -/// Result builder for creating status bar items. +/// A result builder that constructs arrays of status bar items. +/// +/// `StatusBarItemBuilder` enables the declarative syntax for defining multiple +/// items in a status bar. You don't use this type directly; instead, the +/// `@StatusBarItemBuilder` attribute is applied to closures that define +/// status bar content. +/// +/// ## Overview +/// +/// When you write: +/// +/// ```swift +/// .statusBarItems { +/// StatusBarItem(shortcut: .arrowsUpDown, label: "navigate") +/// StatusBarItem(shortcut: .enter, label: "select", key: .enter) +/// StatusBarItem(shortcut: .escape, label: "back") { goBack() } +/// } +/// ``` +/// +/// The `@StatusBarItemBuilder` attribute transforms this closure into an array +/// of ``StatusBarItemProtocol`` conforming items that the status bar can display. +/// +/// ## Supported Control Flow +/// +/// The builder supports: +/// - Multiple item expressions +/// - `if`/`else` conditionals +/// - `if let` optional binding +/// - `for`...`in` loops +/// +/// ## See Also +/// +/// - ``StatusBarItem`` +/// - ``View/statusBarItems(_:)`` @resultBuilder public struct StatusBarItemBuilder { } diff --git a/Sources/TUIkit/Views/ButtonRow.swift b/Sources/TUIkit/Views/ButtonRow.swift index 3fcd442..4582a12 100644 --- a/Sources/TUIkit/Views/ButtonRow.swift +++ b/Sources/TUIkit/Views/ButtonRow.swift @@ -39,7 +39,34 @@ public struct ButtonRow: View { // MARK: - ButtonRow Builder -/// Result builder for creating button rows. +/// A result builder that constructs arrays of buttons for use in ``ButtonRow``. +/// +/// `ButtonRowBuilder` enables the declarative syntax for defining multiple +/// buttons within a ``ButtonRow``. You don't use this type directly; instead, +/// the `@ButtonRowBuilder` attribute is applied to the trailing closure of +/// ``ButtonRow/init(spacing:_:)``. +/// +/// ## Overview +/// +/// When you write: +/// +/// ```swift +/// ButtonRow { +/// Button("Cancel", style: .plain) { dismiss() } +/// Button("OK", style: .primary) { confirm() } +/// } +/// ``` +/// +/// The `@ButtonRowBuilder` attribute transforms this closure into an array +/// of ``Button`` instances that the row can lay out horizontally. +/// +/// ## Supported Control Flow +/// +/// The builder supports: +/// - Multiple button expressions +/// - `if`/`else` conditionals +/// - `if let` optional binding +/// - `for`...`in` loops @resultBuilder public struct ButtonRowBuilder { /// Combines multiple buttons into a single array. diff --git a/Sources/TUIkit/Views/RadioButton.swift b/Sources/TUIkit/Views/RadioButton.swift index 02efebf..e4e424a 100644 --- a/Sources/TUIkit/Views/RadioButton.swift +++ b/Sources/TUIkit/Views/RadioButton.swift @@ -60,7 +60,35 @@ public struct RadioButtonItem { // MARK: - Radio Button Group Builder -/// Result builder for radio button items. +/// A result builder that constructs arrays of radio button items for use in ``RadioButtonGroup``. +/// +/// `RadioButtonGroupBuilder` enables the declarative syntax for defining multiple +/// options within a ``RadioButtonGroup``. You don't use this type directly; instead, +/// the `@RadioButtonGroupBuilder` attribute is applied to the trailing closure of +/// ``RadioButtonGroup/init(selection:orientation:_:)``. +/// +/// ## Overview +/// +/// When you write: +/// +/// ```swift +/// RadioButtonGroup(selection: $choice) { +/// RadioButtonItem(.option1, "First Option") +/// RadioButtonItem(.option2, "Second Option") +/// RadioButtonItem(.option3, "Third Option") +/// } +/// ``` +/// +/// The `@RadioButtonGroupBuilder` attribute transforms this closure into an array +/// of ``RadioButtonItem`` instances that the group can render and manage. +/// +/// ## Supported Control Flow +/// +/// The builder supports: +/// - Multiple item expressions +/// - `if`/`else` conditionals +/// - `if let` optional binding +/// - `for`...`in` loops @resultBuilder public enum RadioButtonGroupBuilder { public static func buildBlock(_ items: RadioButtonItem...) -> [RadioButtonItem] {