From f3d58d8d348f6ff8b630d449d5aa2b313f385492 Mon Sep 17 00:00:00 2001 From: Ray Ryan Date: Fri, 21 Mar 2025 10:04:01 -0700 Subject: [PATCH] Updates kdoc on `onPropsChanged`. It was super confusing, caused a lot of mistakes. --- .../com/squareup/workflow1/StatefulWorkflow.kt | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/workflow-core/src/commonMain/kotlin/com/squareup/workflow1/StatefulWorkflow.kt b/workflow-core/src/commonMain/kotlin/com/squareup/workflow1/StatefulWorkflow.kt index a3174c3092..ed9ab67248 100644 --- a/workflow-core/src/commonMain/kotlin/com/squareup/workflow1/StatefulWorkflow.kt +++ b/workflow-core/src/commonMain/kotlin/com/squareup/workflow1/StatefulWorkflow.kt @@ -787,11 +787,20 @@ public abstract class StatefulWorkflow< ): StateT = initialState(props, snapshot) /** - * Called from [RenderContext.renderChild] instead of [initialState] when the workflow is already - * running. This allows the workflow to detect changes in props, and possibly change its state in - * response. This method is called only if the new props value is not `==` with the old. + * Called immediately before [render] if the parent workflow has provided updated + * [PropsT] that are not `==` to those provided previously. This allows the child + * to update its state based on the new information before rendering. + * + * Note, though, that it is generally a mistake to copy information from [PropsT] + * to [StateT]! [PropsT] is always available via the `renderProps` parameter + * of [render], and as [props][WorkflowAction.Updater.props] for a [WorkflowAction]. + * This method is mainly useful if you need to switch an `enum` or `sealed` [StateT] + * based on [PropsT]. * * Default implementation does nothing. + * + * @return the new [StateT]. [render] is then called immediately with this + * value as `renderProps`. */ public open fun onPropsChanged( old: PropsT,