Update Store.ifLet docs (#500)

* Update `Store.ifLet` docs

* More docs

* Update syntax for old CI

* fix

Author: stephencelis

Examples/TicTacToe/Sources/Views-UIKit/AppViewController.swift

@@ -37,16 +37,16 @@ class AppViewController: UINavigationController {
 
     self.store
       .scope(state: { $0.login }, action: AppAction.login)
-      .ifLet { [weak self] loginStore in
+      .ifLet(then: { [weak self] loginStore in
         self?.setViewControllers([LoginViewController(store: loginStore)], animated: false)
-      }
+      })
       .store(in: &self.cancellables)
 
     self.store
       .scope(state: { $0.newGame }, action: AppAction.newGame)
-      .ifLet { [weak self] newGameStore in
+      .ifLet(then: { [weak self] newGameStore in
         self?.setViewControllers([NewGameViewController(store: newGameStore)], animated: false)
-      }
+      })
       .store(in: &self.cancellables)
   }
 }

Sources/ComposableArchitecture/SwiftUI/TextState.swift

@@ -41,9 +41,9 @@ import SwiftUI
 /// In the future, should `SwiftUI.Text` and `SwiftUI.LocalizedStringKey` reliably conform to
 /// `Equatable`, `TextState` may be deprecated.
 ///
-/// - Note: `TextState` does not support _all_ `LocalizedStringKey` permutations at this time, in
-///   particular, for example interpolated `SwiftUI.Image`s. `TextState` also uses reflection to
-///   determine `LocalizedStringKey` equatability, so look out for edge cases.
+/// - Note: `TextState` does not support _all_ `LocalizedStringKey` permutations at this time
+///   (interpolated `SwiftUI.Image`s, for example. `TextState` also uses reflection to determine
+///   `LocalizedStringKey` equatability, so be mindful of edge cases.
 public struct TextState: Equatable, Hashable {
   fileprivate var modifiers: [Modifier] = []
   fileprivate let storage: Storage

Sources/ComposableArchitecture/UIKit/IfLetUIKit.swift

@@ -1,29 +1,29 @@
 import Combine
 
 extension Store {
-  /// Subscribes to updates when a store containing optional state goes from `nil` to non-`nil` or
-  /// non-`nil` to `nil`.
+  /// Calls one of two closures depending on whether a store's optional state is `nil` or not, and
+  /// whenever this condition changes for as long as the cancellable lives.
   ///
-  /// **NOTE:** one of the `unwrap` or `else` closures is always called based on the *initial* state of the
-  /// optional state (`nil` or non-`nil`), in addition to subsequent changes of `nil` / non-`nil`.
+  /// If the store's state is non-`nil`, it will safely unwrap the value and bundle it into a new
+  /// store of non-optional state that is passed to the first closure. If the store's state is
+  /// `nil`, the second closure is called instead.
   ///
-  /// This is useful for handling navigation in UIKit. The state for a screen that you want to
-  /// navigate to can be held as an optional value in the parent, and when that value switches
-  /// from `nil` to non-`nil` you want to trigger a navigation and hand the detail view a `Store`
-  /// whose domain has been scoped to just that feature:
+  /// This method is useful for handling navigation in UIKit. The state for a screen the user wants
+  /// to navigate to can be held as an optional value in the parent, and when that value goes from
+  /// `nil` to non-`nil`, or non-`nil` to `nil`, you can update the navigation stack accordingly:
   ///
-  ///     class MasterViewController: UIViewController {
-  ///       let store: Store<MasterState, MasterAction>
+  ///     class ParentViewController: UIViewController {
+  ///       let store: Store<ParentState, ParentAction>
   ///       var cancellables: Set<AnyCancellable> = []
   ///       ...
   ///       func viewDidLoad() {
   ///         ...
   ///         self.store
-  ///           .scope(state: \.optionalDetail, action: MasterAction.detail)
+  ///           .scope(state: \.optionalChild, action: ParentAction.child)
   ///           .ifLet(
-  ///             then: { [weak self] detailStore in
+  ///             then: { [weak self] childStore in
   ///               self?.navigationController?.pushViewController(
-  ///                 DetailViewController(store: detailStore),
+  ///                 ChildViewController(store: childStore),
   ///                 animated: true
   ///               )
   ///             },
@@ -37,15 +37,15 @@ extension Store {
   ///     }
   ///
   /// - Parameters:
-  ///   - unwrap: A function that is called with a store of non-optional state whenever the store's
-  ///     optional state is initially non-`nil` or goes from `nil` to non-`nil`.
-  ///   - else: A function that is called whenever the store's optional state is initially `nil` or
+  ///   - unwrap: A function that is called with a store of non-optional state when the store's
+  ///     state is non-`nil`, or whenever it goes from `nil` to non-`nil`.
+  ///   - else: A function that is called when the store's optional state is `nil`, or whenever it
   ///     goes from non-`nil` to `nil`.
-
-  /// - Returns: A cancellable associated with the underlying subscription.
+  /// - Returns: A cancellable that maintains a subscription to updates whenever the store's state
+  ///   goes from `nil` to non-`nil` and vice versa, so that the caller can react to these changes.
   public func ifLet<Wrapped>(
     then unwrap: @escaping (Store<Wrapped, Action>) -> Void,
-    else: @escaping () -> Void
+    else: @escaping () -> Void = {}
   ) -> Cancellable where State == Wrapped? {
     let elseCancellable =
       self
@@ -75,16 +75,4 @@ extension Store {
       unwrapCancellable.cancel()
     }
   }
-
-  /// An overload of `ifLet(then:else:)` for the times that you do not want to handle the `else`
-  /// case.
-  ///
-  /// - Parameter unwrap: A function that is called with a store of non-optional state whenever the
-  ///   store's optional state is initially non-`nil` or goes from `nil` to non-`nil`.
-  /// - Returns: A cancellable associated with the underlying subscription.
-  public func ifLet<Wrapped>(
-    then unwrap: @escaping (Store<Wrapped, Action>) -> Void
-  ) -> Cancellable where State == Wrapped? {
-    self.ifLet(then: unwrap, else: {})
-  }
 }

Tests/ComposableArchitectureTests/StoreTests.swift

@@ -328,23 +328,24 @@ final class StoreTests: XCTestCase {
       environment: ()
     )
 
-    parentStore.ifLet { childStore in
-      let vs = ViewStore(childStore)
-
-      vs
-        .publisher
-        .sink { _ in }
-        .store(in: &self.cancellables)
-
-      vs.send(false)
-      _ = XCTWaiter.wait(for: [.init()], timeout: 0.1)
-      vs.send(false)
-      _ = XCTWaiter.wait(for: [.init()], timeout: 0.1)
-      vs.send(false)
-      _ = XCTWaiter.wait(for: [.init()], timeout: 0.1)
-      XCTAssertEqual(vs.state, 3)
-    }
-    .store(in: &self.cancellables)
+    parentStore
+      .ifLet(then: { childStore in
+        let vs = ViewStore(childStore)
+
+        vs
+          .publisher
+          .sink { _ in }
+          .store(in: &self.cancellables)
+
+        vs.send(false)
+        _ = XCTWaiter.wait(for: [.init()], timeout: 0.1)
+        vs.send(false)
+        _ = XCTWaiter.wait(for: [.init()], timeout: 0.1)
+        vs.send(false)
+        _ = XCTWaiter.wait(for: [.init()], timeout: 0.1)
+        XCTAssertEqual(vs.state, 3)
+      })
+      .store(in: &self.cancellables)
   }
 
   func testActionQueuing() {