Document some more public symbols (#273)

Author: davdroman

CHANGELOG.md

@@ -13,6 +13,7 @@ Changelog
 - Added: `SignInWithAppleButton` introspection (#265)
 - Added: `View` introspection on macOS (#266)
 - Improved: `View` introspection accuracy (#266)
+- Documentation: added some more docs for public symbols (#273)
 
 ### Introspect
 

Sources/Introspect.swift

@@ -1,7 +1,12 @@
 import SwiftUI
 
+/// The scope of introspection i.e. where introspect should look to find
+/// the desired target view relative to the applied `.introspect(...)`
+/// modifier.
 public struct IntrospectionScope: OptionSet {
+    /// Look within the `receiver` of the `.introspect(...)` modifier.
     public static let receiver = Self(rawValue: 1 << 0)
+    /// Look for an `ancestor` relative to the `.introspect(...)` modifier.
     public static let ancestor = Self(rawValue: 1 << 1)
 
     @_spi(Private) public let rawValue: UInt
@@ -12,6 +17,28 @@ public struct IntrospectionScope: OptionSet {
 }
 
 extension View {
+    /// Introspects a SwiftUI view to find its underlying UIKit/AppKit instance.
+    ///
+    /// - Parameters:
+    ///   - viewType: The type of view to be introspected.
+    ///   - platforms: A list of `PlatformViewVersions` that specify platform-specific entities associated with the view, with one or more corresponding version numbers.
+    ///   - scope: An optional `IntrospectionScope` that specifies the scope of introspection.
+    ///   - customize: A closure that hands over the underlying UIKit/AppKit instance ready for customization.
+    ///
+    /// Here's an example usage:
+    ///
+    /// ```swift
+    /// struct ContentView: View {
+    ///     @State var date = Date()
+    ///
+    ///     var body: some View {
+    ///         DatePicker("Pick a date", selection: $date)
+    ///             .introspect(.datePicker, on: .iOS(.v13, .v14, .v15, .v16, .v17)) {
+    ///                 print(type(of: $0)) // UIDatePicker
+    ///             }
+    ///     }
+    /// }
+    /// ```
     public func introspect<SwiftUIViewType: IntrospectableViewType, PlatformSpecificEntity: PlatformEntity>(
         _ viewType: SwiftUIViewType,
         on platforms: (PlatformViewVersions<SwiftUIViewType, PlatformSpecificEntity>)...,

Sources/IntrospectableViewType.swift

@@ -1,4 +1,14 @@
 public protocol IntrospectableViewType {
+    /// The scope of introspection for this particular view type, i.e. where introspect
+    /// should look to find the desired target view relative to the applied
+    /// `.introspect(...)` modifier.
+    ///
+    /// While the scope can be overridden by the user in their `.introspect(...)` call,
+    /// most of the time it's preferable to defer to the view type's own scope,
+    /// as it guarantees introspection is working as intended by the vendor.
+    ///
+    /// Defaults to `.receiver` if left unimplemented, which is a sensible one in
+    /// most cases if you're looking to implement your own view type.
     var scope: IntrospectionScope { get }
 }