Documentation for new SwiftUIIntrospect module (#258)

Author: davdroman

.github/workflows/ci.yml

@@ -117,7 +117,7 @@ jobs:
         name: Install Required Runtime (${{ matrix.runtime }})
         uses: nick-fields/retry@v2
         with:
-          timeout_minutes: 12
+          timeout_minutes: 15
           max_attempts: 3
           command: sudo xcodes runtimes install '${{ matrix.runtime }}'
 

Examples/Showcase/Showcase/Helpers.swift

@@ -1,10 +1,17 @@
 import SwiftUI
 
 extension View {
-    @ViewBuilder
-    func modifier<TransformedView: View>(
-        @ViewBuilder transform: (Self) -> TransformedView
-    ) -> TransformedView {
-        transform(self)
+    /// Modify a view with a `ViewBuilder` closure.
+    ///
+    /// This represents a streamlining of the
+    /// [`modifier`](https://developer.apple.com/documentation/swiftui/view/modifier(_:)) +
+    /// [`ViewModifier`](https://developer.apple.com/documentation/swiftui/viewmodifier) pattern.
+    ///
+    /// - Note: Useful only when you don't need to reuse the closure.
+    /// If you do, turn the closure into a proper modifier.
+    public func modifier<ModifiedContent: View>(
+        @ViewBuilder _ modifier: (Self) -> ModifiedContent
+    ) -> ModifiedContent {
+        modifier(self)
     }
 }

Sources/ViewTypes/Button.swift

@@ -1,10 +1,22 @@
-#if os(macOS)
 import SwiftUI
 
-// MARK: SwiftUI.Button
-
+/// An abstract representation of the `Button` type in SwiftUI.
+///
+/// ```swift
+/// struct ContentView: View {
+///     var body: some View {
+///         Button("Action", action: {})
+///             #if os(macOS)
+///             .introspect(.button, on: .macOS(.v10_15, .v11, .v12, .v13, .v14)) {
+///                 print(type(of: $0)) // NSButton
+///             }
+///             #endif
+///     }
+/// }
+/// ```
 public struct ButtonType: IntrospectableViewType {}
 
+#if os(macOS)
 extension IntrospectableViewType where Self == ButtonType {
     public static var button: Self { .init() }
 }

Sources/ViewTypes/ColorPicker.swift

@@ -1,10 +1,28 @@
-#if !os(tvOS)
 import SwiftUI
 
-// MARK: SwiftUI.ColorPicker
-
+/// An abstract representation of the `ColorPicker` type in SwiftUI.
+///
+/// ```swift
+/// struct ContentView: View {
+///     @State var color = Color.red
+///
+///     var body: some View {
+///         ColorPicker("Pick a color", selection: $color)
+///             #if os(iOS)
+///             .introspect(.colorPicker, on: .iOS(.v14, .v15, .v16, .v17)) {
+///                 print(type(of: $0)) // UIColorPicker
+///             }
+///             #elseif os(macOS)
+///             .introspect(.colorPicker, on: .macOS(.v11, .v12, .v13, .v14)) {
+///                 print(type(of: $0)) // NSColorPicker
+///             }
+///             #endif
+///     }
+/// }
+/// ```
 public struct ColorPickerType: IntrospectableViewType {}
 
+#if !os(tvOS)
 extension IntrospectableViewType where Self == ColorPickerType {
     public static var colorPicker: Self { .init() }
 }

Sources/ViewTypes/DatePicker.swift

@@ -1,10 +1,28 @@
-#if os(iOS) || os(macOS)
 import SwiftUI
 
-// MARK: SwiftUI.DatePicker
-
+/// An abstract representation of the `DatePicker` type in SwiftUI.
+///
+/// ```swift
+/// struct ContentView: View {
+///     @State var date = Date()
+///
+///     var body: some View {
+///         DatePicker("Pick a date", selection: $date)
+///             #if os(iOS)
+///             .introspect(.datePicker, on: .iOS(.v13, .v14, .v15, .v16, .v17)) {
+///                 print(type(of: $0)) // UIDatePicker
+///             }
+///             #elseif os(macOS)
+///             .introspect(.datePicker, on: .macOS(.v10_15, .v11, .v12, .v13, .v14)) {
+///                 print(type(of: $0)) // NSDatePicker
+///             }
+///             #endif
+///     }
+/// }
+/// ```
 public struct DatePickerType: IntrospectableViewType {}
 
+#if os(iOS) || os(macOS)
 extension IntrospectableViewType where Self == DatePickerType {
     public static var datePicker: Self { .init() }
 }

Sources/ViewTypes/DatePickerWithCompactStyle.swift

@@ -1,14 +1,33 @@
-#if os(iOS) || os(macOS)
 import SwiftUI
 
-// MARK: SwiftUI.DatePicker { ... }.datePickerStyle(.compact)
-
+/// An abstract representation of the `DatePicker` type in SwiftUI, with `.compact` style.
+///
+/// ```swift
+/// struct ContentView: View {
+///     @State var date = Date()
+///
+///     var body: some View {
+///         DatePicker("Pick a date", selection: $date)
+///             .datePickerStyle(.compact)
+///             #if os(iOS)
+///             .introspect(.datePicker(style: .compact), on: .iOS(.v14, .v15, .v16, .v17)) {
+///                 print(type(of: $0)) // UIDatePicker
+///             }
+///             #elseif os(macOS)
+///             .introspect(.datePicker(style: .compact), on: .macOS(.v10_15_4, .v11, .v12, .v13, .v14)) {
+///                 print(type(of: $0)) // NSDatePicker
+///             }
+///             #endif
+///     }
+/// }
+/// ```
 public struct DatePickerWithCompactStyleType: IntrospectableViewType {
     public enum Style {
         case compact
     }
 }
 
+#if os(iOS) || os(macOS)
 extension IntrospectableViewType where Self == DatePickerWithCompactStyleType {
     public static func datePicker(style: Self.Style) -> Self { .init() }
 }

Sources/ViewTypes/DatePickerWithFieldStyle.swift

@@ -1,14 +1,29 @@
-#if os(macOS)
 import SwiftUI
 
-// MARK: SwiftUI.DatePicker { ... }.datePickerStyle(.field)
-
+/// An abstract representation of the `DatePicker` type in SwiftUI, with `.field` style.
+///
+/// ```swift
+/// struct ContentView: View {
+///     @State var date = Date()
+///
+///     var body: some View {
+///         DatePicker("Pick a date", selection: $date)
+///             .datePickerStyle(.field)
+///             #if os(macOS)
+///             .introspect(.datePicker(style: .field), on: .macOS(.v10_15, .v11, .v12, .v13, .v14)) {
+///                 print(type(of: $0)) // NSDatePicker
+///             }
+///             #endif
+///     }
+/// }
+/// ```
 public struct DatePickerWithFieldStyleType: IntrospectableViewType {
     public enum Style {
         case field
     }
 }
 
+#if os(macOS)
 extension IntrospectableViewType where Self == DatePickerWithFieldStyleType {
     public static func datePicker(style: Self.Style) -> Self { .init() }
 }

Sources/ViewTypes/DatePickerWithGraphicalStyleType.swift

@@ -1,14 +1,33 @@
-#if os(iOS) || os(macOS)
 import SwiftUI
 
-// MARK: SwiftUI.DatePicker { ... }.datePickerStyle(.graphical)
-
+/// An abstract representation of the `DatePicker` type in SwiftUI, with `.graphical` style.
+///
+/// ```swift
+/// struct ContentView: View {
+///     @State var date = Date()
+///
+///     var body: some View {
+///         DatePicker("Pick a date", selection: $date)
+///             .datePickerStyle(.graphical)
+///             #if os(iOS)
+///             .introspect(.datePicker(style: .graphical), on: .iOS(.v14, .v15, .v16, .v17)) {
+///                 print(type(of: $0)) // UIDatePicker
+///             }
+///             #elseif os(macOS)
+///             .introspect(.datePicker(style: .graphical), on: .macOS(.v10_15, .v11, .v12, .v13, .v14)) {
+///                 print(type(of: $0)) // NSDatePicker
+///             }
+///             #endif
+///     }
+/// }
+/// ```
 public struct DatePickerWithGraphicalStyleType: IntrospectableViewType {
     public enum Style {
         case graphical
     }
 }
 
+#if os(iOS) || os(macOS)
 extension IntrospectableViewType where Self == DatePickerWithGraphicalStyleType {
     public static func datePicker(style: Self.Style) -> Self { .init() }
 }

Sources/ViewTypes/DatePickerWithStepperFieldStyle.swift

@@ -1,14 +1,29 @@
-#if os(macOS)
 import SwiftUI
 
-// MARK: SwiftUI.DatePicker { ... }.datePickerStyle(.stepperField)
-
+/// An abstract representation of the `DatePicker` type in SwiftUI, with `.stepperField` style.
+///
+/// ```swift
+/// struct ContentView: View {
+///     @State var date = Date()
+///
+///     var body: some View {
+///         DatePicker("Pick a date", selection: $date)
+///             .datePickerStyle(.stepperField)
+///             #if os(macOS)
+///             .introspect(.datePicker(style: .stepperField), on: .macOS(.v10_15, .v11, .v12, .v13, .v14)) {
+///                 print(type(of: $0)) // NSDatePicker
+///             }
+///             #endif
+///     }
+/// }
+/// ```
 public struct DatePickerWithStepperFieldStyleType: IntrospectableViewType {
     public enum Style {
         case stepperField
     }
 }
 
+#if os(macOS)
 extension IntrospectableViewType where Self == DatePickerWithStepperFieldStyleType {
     public static func datePicker(style: Self.Style) -> Self { .init() }
 }

Sources/ViewTypes/DatePickerWithWheelStyle.swift

@@ -1,14 +1,29 @@
-#if os(iOS)
 import SwiftUI
 
-// MARK: SwiftUI.DatePicker { ... }.datePickerStyle(.wheel)
-
+/// An abstract representation of the `DatePicker` type in SwiftUI, with `.wheel` style.
+///
+/// ```swift
+/// struct ContentView: View {
+///     @State var date = Date()
+///
+///     var body: some View {
+///         DatePicker("Pick a date", selection: $date)
+///             .datePickerStyle(.wheel)
+///             #if os(iOS)
+///             .introspect(.datePicker(style: .wheel), on: .iOS(.v13, .v14, .v15, .v16, .v17)) {
+///                 print(type(of: $0)) // UIDatePicker
+///             }
+///             #endif
+///     }
+/// }
+/// ```
 public struct DatePickerWithWheelStyleType: IntrospectableViewType {
     public enum Style {
         case wheel
     }
 }
 
+#if os(iOS)
 extension IntrospectableViewType where Self == DatePickerWithWheelStyleType {
     public static func datePicker(style: Self.Style) -> Self { .init() }
 }