From f4597ac7246bb57b9d112e714f0aebd8daf9733e Mon Sep 17 00:00:00 2001 From: Ray Ryan Date: Thu, 18 Jan 2024 14:39:39 -0800 Subject: [PATCH 1/3] Document how WorkflowAction can delegate It's an obscure use case, but it comes up every now and then --- .../com/squareup/workflow1/WorkflowAction.kt | 20 +++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/workflow-core/src/commonMain/kotlin/com/squareup/workflow1/WorkflowAction.kt b/workflow-core/src/commonMain/kotlin/com/squareup/workflow1/WorkflowAction.kt index 3ced69868..753388030 100644 --- a/workflow-core/src/commonMain/kotlin/com/squareup/workflow1/WorkflowAction.kt +++ b/workflow-core/src/commonMain/kotlin/com/squareup/workflow1/WorkflowAction.kt @@ -10,12 +10,28 @@ import kotlin.jvm.JvmOverloads /** * An atomic operation that updates the state of a [Workflow], and also optionally emits an output. + * + * A [WorkflowAction]'s [apply] method is executed in the context of an [Updater][WorkflowAction.Updater], + * which provides access to the current [props][WorkflowAction.Updater.props] and + * [state][WorkflowAction.Updater.props]. The latter can be updated with a new [StateT] instance + * that will become the current one after the [apply] function finishes. + * + * It is possible for one [WorkflowAction] to delegate to another, although the API is a bit opaque: + * + * val actionA = action { + * } + * + * val actionB = action { + * val (newState, outputApplied) = actionA.applyTo(props, state) + * state = newState + * outputApplied.output?.value?.let { setOutput(it) } + * } */ public abstract class WorkflowAction { /** - * The context for calls to [WorkflowAction.apply]. Allows the action to set the - * [state], and to emit the [setOutput]. + * The context for calls to [WorkflowAction.apply]. Allows the action to read and change the + * [state], and to emit an [output][setOutput] value. * * @param state the state that the workflow should move to. Default is the current state. */ From f1df4da12d4565db64508bb0a1e382d96849ba3a Mon Sep 17 00:00:00 2001 From: Ray Ryan Date: Thu, 18 Jan 2024 14:42:44 -0800 Subject: [PATCH 2/3] Tweak WorkflowAction kdoc --- .../kotlin/com/squareup/workflow1/WorkflowAction.kt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/workflow-core/src/commonMain/kotlin/com/squareup/workflow1/WorkflowAction.kt b/workflow-core/src/commonMain/kotlin/com/squareup/workflow1/WorkflowAction.kt index 753388030..9e4caab48 100644 --- a/workflow-core/src/commonMain/kotlin/com/squareup/workflow1/WorkflowAction.kt +++ b/workflow-core/src/commonMain/kotlin/com/squareup/workflow1/WorkflowAction.kt @@ -13,7 +13,9 @@ import kotlin.jvm.JvmOverloads * * A [WorkflowAction]'s [apply] method is executed in the context of an [Updater][WorkflowAction.Updater], * which provides access to the current [props][WorkflowAction.Updater.props] and - * [state][WorkflowAction.Updater.props]. The latter can be updated with a new [StateT] instance + * [state][WorkflowAction.Updater.state], + * along with a [setOutput][WorkflowAction.Updater.setOutput] function. + * The [state][WorkflowAction.Updater.state] can be updated with a new [StateT] instance * that will become the current one after the [apply] function finishes. * * It is possible for one [WorkflowAction] to delegate to another, although the API is a bit opaque: From f43e7de846f0c4f739897211b6eec13614dc6e44 Mon Sep 17 00:00:00 2001 From: rjrjr Date: Thu, 18 Jan 2024 22:46:44 +0000 Subject: [PATCH 3/3] Apply changes from ktLintFormat Signed-off-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- .../commonMain/kotlin/com/squareup/workflow1/WorkflowAction.kt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/workflow-core/src/commonMain/kotlin/com/squareup/workflow1/WorkflowAction.kt b/workflow-core/src/commonMain/kotlin/com/squareup/workflow1/WorkflowAction.kt index 9e4caab48..247183dbf 100644 --- a/workflow-core/src/commonMain/kotlin/com/squareup/workflow1/WorkflowAction.kt +++ b/workflow-core/src/commonMain/kotlin/com/squareup/workflow1/WorkflowAction.kt @@ -22,7 +22,7 @@ import kotlin.jvm.JvmOverloads * * val actionA = action { * } - * + * * val actionB = action { * val (newState, outputApplied) = actionA.applyTo(props, state) * state = newState