more dismisseffect docs

Author: mbrandonw

Sources/ComposableArchitecture/Dependencies/Dismiss.swift

@@ -3,31 +3,7 @@ import SwiftUI
 extension DependencyValues {
   /// An effect that dismisses the current presentation.
   ///
-  /// Execute this in the effect returned from a reducer in order to dismiss the feature:
-  ///
-  /// ```swift
-  /// struct ChildFeature: ReducerProtocol {
-  ///   struct State { /* ... */ }
-  ///   enum Action {
-  ///     case exitButtonTapped
-  ///     // ...
-  ///   }
-  ///   @Dependency(\.dismiss) var dismiss
-  ///   func reduce(into state: inout State, action: Action) -> EffectTask<Action> {
-  ///     switch action {
-  ///       case .exitButtonTapped:
-  ///         return .fireAndForget { await self.dismiss() }
-  ///       // ...
-  ///     }
-  ///   }
-  /// }
-  /// ```
-  ///
-  /// This operation works by finding the nearest parent feature that was presented using either the
-  /// ``ReducerProtocol/ifLet(_:action:destination:fileID:line:)`` or the
-  /// ``ReducerProtocol/forEach(_:action:destination:fileID:line:)`` operator, and then
-  /// dismisses _that_ feature. If no such parent feature is found a runtime warning is emitted in
-  /// Xcode letting you know that it is not possible to dismiss.
+  /// See the documentation of ``DismissEffect`` for more information.
   public var dismiss: DismissEffect {
     get { self[DismissKey.self] }
     set { self[DismissKey.self] = newValue }
@@ -58,9 +34,43 @@ extension DependencyValues {
 ///
 /// This operation works by finding the nearest parent feature that was presented using either the
 /// ``ReducerProtocol/ifLet(_:action:destination:fileID:line:)`` or the
-/// ``ReducerProtocol/forEach(_:action:destination:fileID:line:)`` operator, and then dismisses
-/// _that_ feature. If no such parent feature is found a runtime warning is emitted in Xcode letting
-/// you know that it is not possible to dismiss.
+/// ``ReducerProtocol/forEach(_:action:destination:fileID:line:)`` operator, and then
+/// dismisses _that_ feature. It performs the dismissal by either sending the
+/// ``PresentationAction/dismiss`` in the case of `ifLet` or sending ``StackAction/popFrom(id:)``
+/// in the case of `forEach`.
+///
+/// It is also possible to dismiss the feature using an animation by providing an argument to the
+/// `dismiss` function:
+///
+/// ```swift
+/// case .exitButtonTapped:
+///   return .fireAndForget { await self.dismiss(animation: .default) }
+/// ```
+///
+/// This will cause the `dismiss` or `popFrom(id:)` action to be sent with the particular animation.
+///
+/// > Warning: The `@Dependency(\.dismiss)` tool only works for features that are presented using
+/// > the `ifLet` operator for tree-based navigation (see <doc:TreeBasedNavigation> for more info)
+/// > or `forEach` operator for stack-based navigation (see <doc:StackBasedNavigation>). If no
+/// > parent feature is found that was presented with `ifLet` or `forEach`, then a runtime warning
+/// > is emitted in Xcode letting you know that it is not possible to dismiss. Further, the runtime
+/// > warning becomes a test failure when run in tests.
+/// >
+/// > If you are testing a child feature in isolation that makes use of `@Dependency(\.dismiss)`
+/// > then you will need to override the dependency to get a passing test. You can even mutate
+/// > some shared mutable state inside the `dismiss` closure to confirm that it is indeed invoked:
+/// >
+/// > ```swift
+/// > let isDismissInvoked = LockIsolated(false)
+/// > let store = Store(initialState: Child.State(), reducer: Child()) {
+/// >   $0.dismiss = { isDismissInvoked.setValue(true) }
+/// > }
+/// >
+/// > await store.send(.exitButtonTapped) {
+/// >   // ...
+/// > }
+/// > XCTAssertEqual(isDismissInvoked.value, true)
+/// > ```
 public struct DismissEffect: Sendable {
   var dismiss: (@MainActor @Sendable () -> Void)?
 

Sources/ComposableArchitecture/Documentation.docc/ComposableArchitecture.md

@@ -65,7 +65,7 @@ day-to-day when building applications, such as:
 - ``Store``
 - ``ViewStore``
 
-### Navigation
+### Navigation tools
 
 - <doc:Navigation>
 - ``PresentationState``
@@ -74,6 +74,7 @@ day-to-day when building applications, such as:
 - ``StackState``
 - ``StackAction``
 - ``ReducerProtocol/forEach(_:action:destination:fileID:line:)``
+- ``DismissEffect``
 
 ### Integrations