[docs]: update some docs per PR feedback

Author: jamieQ

Workflow/Sources/ApplyContext.swift

@@ -24,8 +24,39 @@ protocol ApplyContextType<WorkflowType> {
 }
 
 /// Runtime context passed as a parameter to `WorkflowAction`'s `apply()` method
-/// that provides an integration point with the runtime that can be used to read property values
-/// off of the current `Workflow` instance.
+/// that provides an integration point with the runtime that can be used to read values from
+/// the current `Workflow` instance.
+///
+/// Read-only access to `Workflow` values is exposed via the `subscript[workflowValue:]` API,
+/// which accepts a read-only `KeyPath` to a `Workflow`'s value.
+///
+/// Usage example:
+///
+/// ```swift
+///     struct MyWorkflow: Workflow {
+///         let shouldSuppressOutput: Bool
+///
+///         // ... implementation ...
+///     }
+///
+///     enum MyAction: WorkflowAction {
+///         typealias WorkflowType = MyWorkflow
+///
+///         case one
+///         case two
+///
+///         func apply(toState state: inout WorkflowType.State, context: ApplyContext<WorkflowType>) -> WorkflowType.Output? {
+///             // Make conditional choices based on the `Workflow`'s instance values
+///             let shouldSuppressOutput = context[workflowValue: \.shouldSuppressOutput]
+///             if shouldSuppressOutput { return nil }
+///
+///             // ... implementation ...
+///         }
+///     }
+/// ```
+///
+/// > Warning: The instance of this type passed to the `apply()` method should not escape from that method.
+/// Attempting to access the instance after the `apply()` method has returned is a client error and will crash.
 public struct ApplyContext<WorkflowType: Workflow> {
     let wrappedContext: any ApplyContextType<WorkflowType>
 

Workflow/Sources/WorkflowAction.swift

@@ -24,9 +24,12 @@ public protocol WorkflowAction<WorkflowType> {
     ///
     /// - Parameter state: The current state of the workflow. The state is passed as an `inout` param, allowing actions
     ///                    to modify state during application.
+    /// - Parameter context: A context object provided by the runtime that enables reading values of the underlying `Workflow` instance.
     ///
     /// - Returns: An optional output event for the workflow. If an output event is returned, it will be passed up
     ///            the workflow hierarchy to this workflow's parent.
+    /// > Warning: The `context` parameter should not escape from implementations of this requirement.
+    /// Attempting to access the instance after `apply()` has returned is a client error and will crash.
     func apply(
         toState state: inout WorkflowType.State,
         context: ApplyContext<WorkflowType>

Workflow/Sources/WorkflowNode.swift

@@ -219,7 +219,7 @@ extension WorkflowNode {
 
         /// Apply the action to the current state
         do {
-            // TODO: can we avoid instantiating a class here somehow?
+            // FIXME: can we avoid instantiating a class here somehow?
             let context = ConcreteApplyContext(storage: workflow)
             defer { context.invalidate() }
 

WorkflowTesting/Sources/WorkflowActionTester.swift

@@ -190,8 +190,9 @@ extension WorkflowActionTester where WorkflowType.Output: Equatable {
 struct TestApplyContext<Wrapped: Workflow>: ApplyContextType {
     enum TestContextKind {
         case workflow(Wrapped)
-        // TODO: flesh this out to support 'just in time' values
+        // FIXME: flesh this out to support 'just in time' values
         // rather than requiring a full Workflow instance to be provided
+        // https://github.com/square/workflow-swift/issues/351
         case expectations([AnyKeyPath: Any])
     }
 

WorkflowTesting/Tests/WorkflowActionTesterTests.swift

@@ -117,7 +117,7 @@ extension WorkflowActionTesterTests {
             .assert(output: .value("read props: 42"))
     }
 
-    // TODO: ideally an 'exit/death test' would be used for this...
+    // FIXME: ideally an 'exit/death test' would somehow be used for this...
     /*
      func test_old_api_explodes_if_you_use_props() {
          XCTExpectFailure("This test should fail")