Repository: square/workflow-kotlin
Issue: Fix kdoc references to RenderContext

A lot of kdoc references were broken by #97, these should be fixed before 1.0.0 final, not necessarily before 1.0.0-beta though.

Changed files:
workflow-core/src/main/java/com/squareup/workflow1/WorkerWorkflow.kt
workflow-core/src/main/java/com/squareup/workflow1/Worker.kt
workflow-core/src/main/java/com/squareup/workflow1/StatefulWorkflow.kt
workflow-core/src/main/java/com/squareup/workflow1/Sink.kt
workflow-runtime/src/main/java/com/squareup/workflow1/internal/WorkflowNode.kt
workflow-testing/src/main/java/com/squareup/workflow1/testing/RenderIdempotencyChecker.kt
workflow-testing/src/main/java/com/squareup/workflow1/testing/RenderTester.kt
workflow-core/src/main/java/com/squareup/workflow1/BaseRenderContext.kt
workflow-core/src/main/java/com/squareup/workflow1/Workflow.kt

diff --git a/workflow-core/src/main/java/com/squareup/workflow1/BaseRenderContext.kt b/workflow-core/src/main/java/com/squareup/workflow1/BaseRenderContext.kt
index 01bacbe0..4f7a4c11 100644
--- a/workflow-core/src/main/java/com/squareup/workflow1/BaseRenderContext.kt
+++ b/workflow-core/src/main/java/com/squareup/workflow1/BaseRenderContext.kt
@@ -4,7 +4,6 @@
 
 package com.squareup.workflow1
 
-import com.squareup.workflow1.StatefulWorkflow.RenderContext
 import com.squareup.workflow1.WorkflowAction.Companion.noAction
 import kotlinx.coroutines.CoroutineScope
 import kotlin.reflect.KType
@@ -229,7 +228,7 @@ public fun <EventT : Any, PropsT, StateT, OutputT>
 }
 
 /**
- * Convenience alias of [RenderContext.renderChild] for workflows that don't take props.
+ * Convenience alias of [BaseRenderContext.renderChild] for workflows that don't take props.
  */
 public fun <PropsT, StateT, OutputT, ChildOutputT, ChildRenderingT>
   BaseRenderContext<PropsT, StateT, OutputT>.renderChild(
@@ -238,7 +237,7 @@ public fun <PropsT, StateT, OutputT, ChildOutputT, ChildRenderingT>
   handler: (ChildOutputT) -> WorkflowAction<PropsT, StateT, OutputT>
 ): ChildRenderingT = renderChild(child, Unit, key, handler)
 /**
- * Convenience alias of [RenderContext.renderChild] for workflows that don't emit output.
+ * Convenience alias of [BaseRenderContext.renderChild] for workflows that don't emit output.
  */
 public fun <PropsT, ChildPropsT, StateT, OutputT, ChildRenderingT>
   BaseRenderContext<PropsT, StateT, OutputT>.renderChild(
@@ -247,7 +246,7 @@ public fun <PropsT, ChildPropsT, StateT, OutputT, ChildRenderingT>
   key: String = ""
 ): ChildRenderingT = renderChild(child, props, key) { noAction() }
 /**
- * Convenience alias of [RenderContext.renderChild] for children that don't take props or emit
+ * Convenience alias of [BaseRenderContext.renderChild] for children that don't take props or emit
  * output.
  */
 public fun <PropsT, StateT, OutputT, ChildRenderingT>
@@ -321,7 +320,7 @@ val workerWorkflow = WorkerWorkflow<T>(workerType, key)
 }
 
 /**
- * Alternative to [RenderContext.actionSink] that allows externally defined
+ * Alternative to [BaseRenderContext.actionSink] that allows externally defined
  * event types to be mapped to anonymous [WorkflowAction]s.
  */
 @Deprecated("Use BaseRenderContext.eventHandler")
diff --git a/workflow-core/src/main/java/com/squareup/workflow1/Sink.kt b/workflow-core/src/main/java/com/squareup/workflow1/Sink.kt
index c9b88341..3181c0f7 100644
--- a/workflow-core/src/main/java/com/squareup/workflow1/Sink.kt
+++ b/workflow-core/src/main/java/com/squareup/workflow1/Sink.kt
@@ -10,7 +10,7 @@ import kotlin.coroutines.resume
 
 /**
  * An object that receives values (commonly events or [WorkflowAction]).
- * [RenderContext.actionSink] implements this interface.
+ * [BaseRenderContext.actionSink] implements this interface.
  */
 public fun interface Sink<in T> {
   public fun send(value: T)
@@ -43,7 +43,7 @@ public fun <T1, T2> Sink<T1>.contraMap(transform: (T2) -> T1): Sink<T2> = Sink {
  * is a lot of contention on the workflow runtime the flow will be suspended while the action is
  * queued.
  *
- * This method is intended to be used from [RenderContext.runningSideEffect].
+ * This method is intended to be used from [BaseRenderContext.runningSideEffect].
  *
  * Example:
  * ```
@@ -74,7 +74,7 @@ internal suspend fun <T, PropsT, StateT, OutputT> Flow<T>.collectToSink(
  *
  * If this coroutine is cancelled before the action gets applied, the action will not be applied.
  *
- * This method is intended to be used from [RenderContext.runningSideEffect].
+ * This method is intended to be used from [BaseRenderContext.runningSideEffect].
  */
 @ExperimentalWorkflowApi
 internal suspend fun <
diff --git a/workflow-core/src/main/java/com/squareup/workflow1/StatefulWorkflow.kt b/workflow-core/src/main/java/com/squareup/workflow1/StatefulWorkflow.kt
index d02a04e5..e6b76eb7 100644
--- a/workflow-core/src/main/java/com/squareup/workflow1/StatefulWorkflow.kt
+++ b/workflow-core/src/main/java/com/squareup/workflow1/StatefulWorkflow.kt
@@ -26,9 +26,9 @@ import com.squareup.workflow1.WorkflowAction.Companion.toString
  * [output events][OutputT] up to its parent `Workflow`.
  *
  * Workflows form a tree, where each workflow can have zero or more child workflows. Child workflows
- * are started as necessary whenever another workflow asks for them, and are cleaned up automatically
- * when they're no longer needed. [Props][PropsT] propagate down the tree, [outputs][OutputT] and
- * [renderings][RenderingT] propagate up the tree.
+ * are started as necessary whenever another workflow asks for them, and are cleaned up
+ * automatically when they're no longer needed. [Props][PropsT] propagate down the tree,
+ * [outputs][OutputT] and [renderings][RenderingT] propagate up the tree.
  *
  * ## Avoid capturing stale state
  *
diff --git a/workflow-core/src/main/java/com/squareup/workflow1/Worker.kt b/workflow-core/src/main/java/com/squareup/workflow1/Worker.kt
index 572e8ec1..945d28e7 100644
--- a/workflow-core/src/main/java/com/squareup/workflow1/Worker.kt
+++ b/workflow-core/src/main/java/com/squareup/workflow1/Worker.kt
@@ -30,7 +30,7 @@ import kotlin.reflect.typeOf
  * perform their tasks, workers return a [Flow]. Workers are effectively [Flow]s that can be
  * [compared][doesSameWorkAs] to determine equivalence between render passes. A [Workflow] uses
  * Workers to perform asynchronous work during the render pass by calling
- * [RenderContext.runningWorker].
+ * [BaseRenderContext.runningWorker].
  *
  * See the documentation on [run] for more information on the returned [Flow] is consumed and how
  * to implement asynchronous work.
@@ -133,9 +133,9 @@ public interface Worker<out OutputT> {
    * worker's logic should wrap any relevant exceptions into an output value (e.g. using the
    * [catch][kotlinx.coroutines.flow.catch] operator).
    *
-   * While this might seem restrictive, this design decision keeps the [RenderContext.runningWorker]
-   * API simpler, since it does not need to handle exceptions itself. It also discourages the code
-   * smell of relying on exceptions to handle control flow.
+   * While this might seem restrictive, this design decision keeps the
+   * [BaseRenderContext.runningWorker] API simpler, since it does not need to handle exceptions
+   * itself. It also discourages the code smell of relying on exceptions to handle control flow.
    */
   public fun run(): Flow<OutputT>
 
@@ -194,7 +194,7 @@ public interface Worker<out OutputT> {
 
     /**
      * Creates a [Worker] that just performs some side effects and doesn't emit anything. Run the
-     * worker from your `render` method using [RenderContext.runningWorker].
+     * worker from your `render` method using [BaseRenderContext.runningWorker].
      *
      * E.g.:
      * ```
@@ -205,7 +205,8 @@ public interface Worker<out OutputT> {
      * Note that all workers created with this method are equivalent from the point of view of
      * their [Worker.doesSameWorkAs] methods. A workflow that needs multiple simultaneous
      * side effects can either bundle them all together into a single `createSideEffect`
-     * call, or can use the `key` parameter to [RenderContext.runningWorker] to prevent conflicts.
+     * call, or can use the `key` parameter to [BaseRenderContext.runningWorker] to prevent
+     * conflicts.
      * ```
      */
     public fun createSideEffect(
diff --git a/workflow-core/src/main/java/com/squareup/workflow1/WorkerWorkflow.kt b/workflow-core/src/main/java/com/squareup/workflow1/WorkerWorkflow.kt
index b099b36c..bb08df6b 100644
--- a/workflow-core/src/main/java/com/squareup/workflow1/WorkerWorkflow.kt
+++ b/workflow-core/src/main/java/com/squareup/workflow1/WorkerWorkflow.kt
@@ -23,8 +23,8 @@ import kotlin.reflect.KType
  * to determine whether to restart workers during the lifetime of a single runtime instance.
  *
  * @param workerType The [KType] representing the particular type of `Worker<OutputT>`.
- * @param key The key used to render this workflow, as passed to [RenderContext.runningWorker].
- * Used for naming the worker's coroutine.
+ * @param key The key used to render this workflow, as passed to
+ * [BaseRenderContext.runningWorker]. Used for naming the worker's coroutine.
  */
 @OptIn(ExperimentalWorkflowApi::class)
 internal class WorkerWorkflow<OutputT>(
@@ -34,7 +34,7 @@ internal class WorkerWorkflow<OutputT>(
     ImpostorWorkflow {
 
   override val realIdentifier: WorkflowIdentifier = unsnapshottableIdentifier(workerType)
-  override fun describeRealIdentifier(): String? = "worker $workerType"
+  override fun describeRealIdentifier(): String = "worker $workerType"
 
   override fun initialState(
     props: Worker<OutputT>,
@@ -63,7 +63,7 @@ internal class WorkerWorkflow<OutputT>(
 }
 
 /**
- * Does the actual running of a worker passed to [RenderContext.runningWorker] by setting up the
+ * Does the actual running of a worker passed to [BaseRenderContext.runningWorker] by setting up the
  * coroutine environment for the worker, performing some validation, etc., and finally actually
  * collecting the worker's [Flow].
  *
diff --git a/workflow-core/src/main/java/com/squareup/workflow1/Workflow.kt b/workflow-core/src/main/java/com/squareup/workflow1/Workflow.kt
index 3c86b386..42c82ec4 100644
--- a/workflow-core/src/main/java/com/squareup/workflow1/Workflow.kt
+++ b/workflow-core/src/main/java/com/squareup/workflow1/Workflow.kt
@@ -4,15 +4,16 @@
 package com.squareup.workflow1
 
 /**
- * A composable, optionally-stateful object that can [handle events][RenderContext.onEvent],
- * [delegate to children][RenderContext.renderChild], [subscribe][RenderContext.onWorkerOutput] to
- * arbitrary asynchronous events from the outside world.
+ * A composable, optionally-stateful object that can [handle events][BaseRenderContext.onEvent],
+ * [delegate to children][BaseRenderContext.renderChild],
+ * [subscribe][BaseRenderContext.onWorkerOutput] to arbitrary asynchronous events from the
+ * outside world.
  *
  * The basic purpose of a `Workflow` is to take some input (in the form of [PropsT]) and
  * return a [rendering][RenderingT]. To that end, a workflow may keep track of internal
  * [state][StatefulWorkflow], recursively ask other workflows to render themselves, subscribe to
  * data streams from the outside world, and handle events both from its
- * [renderings][RenderContext.onEvent] and from workflows it's delegated to (its "children"). A
+ * [renderings][BaseRenderContext.onEvent] and from workflows it's delegated to (its "children"). A
  * `Workflow` may also emit [output events][OutputT] up to its parent `Workflow`.
  *
  * Workflows form a tree, where each workflow can have zero or more child workflows. Child workflows
@@ -49,11 +50,11 @@ package com.squareup.workflow1
  *
  * ## Interacting with events and other workflows
  *
- * All workflows are passed a [RenderContext] in their render methods. This context allows the
- * workflow to interact with the outside world by doing things like listening for events,
- * subscribing to streams of data, rendering child workflows, and performing cleanup when the
- * workflow is about to be torn down by its parent. See the documentation on [RenderContext] for
- * more information about what it can do.
+ * All workflows are passed a [RenderContext][BaseRenderContext] in their render methods.
+ * This context allows the workflow to interact with the outside world by doing things like
+ * listening for events, subscribing to streams of data, rendering child workflows, and performing
+ * cleanup when the workflow is about to be torn down by its parent. See the documentation on
+ * [BaseRenderContext] for more information about what it can do.
  *
  * ## Things to avoid
  *
@@ -96,7 +97,7 @@ public interface Workflow<in PropsT, out OutputT, out RenderingT> {
 
   /**
    * Provides a [StatefulWorkflow] view of this workflow. Necessary because [StatefulWorkflow] is
-   * the common API required for [RenderContext.renderChild] to do its work.
+   * the common API required for [BaseRenderContext.renderChild] to do its work.
    */
   public fun asStatefulWorkflow(): StatefulWorkflow<PropsT, *, OutputT, RenderingT>
 
@@ -129,8 +130,7 @@ public fun <PropsT, OutputT, FromRenderingT, ToRenderingT>
       return transform(rendering)
     }
 
-    override fun describeRealIdentifier(): String? =
-      "${this@mapRendering.identifier}.mapRendering()"
+    override fun describeRealIdentifier(): String = "${this@mapRendering.identifier}.mapRendering()"
 
     override fun toString(): String = "${this@mapRendering}.mapRendering()"
   }
diff --git a/workflow-runtime/src/main/java/com/squareup/workflow1/internal/WorkflowNode.kt b/workflow-runtime/src/main/java/com/squareup/workflow1/internal/WorkflowNode.kt
index 140666a4..3d08e395 100644
--- a/workflow-runtime/src/main/java/com/squareup/workflow1/internal/WorkflowNode.kt
+++ b/workflow-runtime/src/main/java/com/squareup/workflow1/internal/WorkflowNode.kt
@@ -32,7 +32,7 @@ import kotlin.coroutines.CoroutineContext
  *
  * @param emitOutputToParent A function that this node will call when it needs to emit an output
  * value to its parent. Returns either the output to be emitted from the root workflow, or null.
- * @param workerContext [CoroutineContext] that is appended to the end of the context used to launch
+ * @param baseContext [CoroutineContext] that is appended to the end of the context used to launch
  * worker coroutines. This context will override anything from the workflow's scope and any other
  * hard-coded values added to worker contexts. It must not contain a [Job] element (it would violate
  * structured concurrency).
@@ -61,7 +61,7 @@ internal class WorkflowNode<PropsT, StateT, OutputT, RenderingT>(
   override val renderKey: String get() = id.name
   override val sessionId: Long = idCounter.createId()
 
-  private val subtreeManager = SubtreeManager<PropsT, StateT, OutputT>(
+  private val subtreeManager = SubtreeManager(
       snapshotCache = snapshot?.childTreeSnapshots,
       contextForChildren = coroutineContext,
       emitActionToParent = ::applyAction,
@@ -94,7 +94,7 @@ internal class WorkflowNode<PropsT, StateT, OutputT, RenderingT>(
 
   /**
    * Walk the tree of workflows, rendering each one and using
-   * [RenderContext][com.squareup.workflow1.RenderContext] to give its children a chance to
+   * [RenderContext][com.squareup.workflow1.BaseRenderContext] to give its children a chance to
    * render themselves and aggregate those child renderings.
    */
   @Suppress("UNCHECKED_CAST")
diff --git a/workflow-testing/src/main/java/com/squareup/workflow1/testing/RenderIdempotencyChecker.kt b/workflow-testing/src/main/java/com/squareup/workflow1/testing/RenderIdempotencyChecker.kt
index dc273abf..0e3942d4 100644
--- a/workflow-testing/src/main/java/com/squareup/workflow1/testing/RenderIdempotencyChecker.kt
+++ b/workflow-testing/src/main/java/com/squareup/workflow1/testing/RenderIdempotencyChecker.kt
@@ -2,7 +2,6 @@ package com.squareup.workflow1.testing
 
 import com.squareup.workflow1.BaseRenderContext
 import com.squareup.workflow1.ExperimentalWorkflowApi
-import com.squareup.workflow1.RenderContext
 import com.squareup.workflow1.Workflow
 import com.squareup.workflow1.WorkflowAction
 import com.squareup.workflow1.WorkflowInterceptor
@@ -41,8 +40,8 @@ public object RenderIdempotencyChecker : WorkflowInterceptor {
 }
 
 /**
- * A [RenderContext] that can record the result of rendering children over a render pass, and then
- * play them back over a second render pass that doesn't actually perform any actions.
+ * A [RenderContextInterceptor] that can record the result of rendering children over a render pass,
+ * and then play them back over a second render pass that doesn't actually perform any actions.
  */
 @OptIn(ExperimentalWorkflowApi::class)
 private class RecordingContextInterceptor<PropsT, StateT, OutputT> :
diff --git a/workflow-testing/src/main/java/com/squareup/workflow1/testing/RenderTester.kt b/workflow-testing/src/main/java/com/squareup/workflow1/testing/RenderTester.kt
index ed562323..48ed5a6b 100644
--- a/workflow-testing/src/main/java/com/squareup/workflow1/testing/RenderTester.kt
+++ b/workflow-testing/src/main/java/com/squareup/workflow1/testing/RenderTester.kt
@@ -237,8 +237,8 @@ public abstract class RenderTester<PropsT, StateT, OutputT, RenderingT> {
    * If false, the match will only be used if no other expectations return exclusive matches (in
    * which case the first match will be used), and the expectation may match multiple side effects.
    * @param matcher A function that is passed the key value from
-   * [runningSideEffect][com.squareup.workflow1.RenderContext.runningSideEffect] and return true if
-   * this key is expected.
+   * [runningSideEffect][com.squareup.workflow1.BaseRenderContext.runningSideEffect] and return
+   * true if this key is expected.
    */
   public abstract fun expectSideEffect(
     description: String,
@@ -269,7 +269,7 @@ public abstract class RenderTester<PropsT, StateT, OutputT, RenderingT> {
 
   /**
    * Describes a call to
-   * [RenderContext.renderChild][com.squareup.workflow1.RenderContext.renderChild].
+   * [RenderContext.renderChild][com.squareup.workflow1.BaseRenderContext.renderChild].
    *
    * ## Output and rendering types
    *
@@ -353,14 +353,12 @@ public abstract class RenderTester<PropsT, StateT, OutputT, RenderingT> {
  * of the actual rendered workflow, e.g. if the workflow type is an interface and the
  * workflow-under-test injects a fake.
  * @param rendering The rendering to return from
- * [renderChild][com.squareup.workflow1.RenderContext.renderChild] when this workflow is rendered.
- * @param key The key passed to [renderChild][com.squareup.workflow1.RenderContext.renderChild]
+ * [renderChild][com.squareup.workflow1.BaseRenderContext.renderChild] when this workflow is
+ * rendered.
+ * @param key The key passed to [renderChild][com.squareup.workflow1.BaseRenderContext.renderChild]
  * when rendering this workflow.
  * @param assertProps A function that performs assertions on the props passed to
- * [renderChild][com.squareup.workflow1.RenderContext.renderChild].
- * @param output If non-null, [WorkflowOutput.value] will be "emitted" when this workflow is
- * rendered. The [WorkflowAction] used to handle this output can be verified using methods on
- * [RenderTestResult].
+ * [renderChild][com.squareup.workflow1.BaseRenderContext.renderChild].
  * @param description Optional string that will be used to describe this expectation in error
  * messages.
  */
@@ -413,11 +411,12 @@ public inline fun <ChildRenderingT, PropsT, StateT, OutputT, RenderingT>
  * of the actual rendered workflow, e.g. if the workflow type is an interface and the
  * workflow-under-test injects a fake.
  * @param rendering The rendering to return from
- * [renderChild][com.squareup.workflow1.RenderContext.renderChild] when this workflow is rendered.
- * @param key The key passed to [renderChild][com.squareup.workflow1.RenderContext.renderChild]
+ * [renderChild][com.squareup.workflow1.BaseRenderContext.renderChild] when this workflow is
+ * rendered.
+ * @param key The key passed to [renderChild][com.squareup.workflow1.BaseRenderContext.renderChild]
  * when rendering this workflow.
  * @param assertProps A function that performs assertions on the props passed to
- * [renderChild][com.squareup.workflow1.RenderContext.renderChild].
+ * [renderChild][com.squareup.workflow1.BaseRenderContext.renderChild].
  * @param output If non-null, [WorkflowOutput.value] will be "emitted" when this workflow is
  * rendered. The [WorkflowAction] used to handle this output can be verified using methods on
  * [RenderTestResult].
@@ -487,11 +486,12 @@ public fun <ChildOutputT, ChildRenderingT, PropsT, StateT, OutputT, RenderingT>
  * of the expected workflow, e.g. if the workflow type is an interface and the workflow-under-test
  * injects a fake.
  * @param rendering The rendering to return from
- * [renderChild][com.squareup.workflow1.RenderContext.renderChild] when this workflow is rendered.
- * @param key The key passed to [renderChild][com.squareup.workflow1.RenderContext.renderChild]
+ * [renderChild][com.squareup.workflow1.BaseRenderContext.renderChild] when this workflow is
+ * rendered.
+ * @param key The key passed to [renderChild][com.squareup.workflow1.BaseRenderContext.renderChild]
  * when rendering this workflow.
  * @param assertProps A function that performs assertions on the props passed to
- * [renderChild][com.squareup.workflow1.RenderContext.renderChild].
+ * [renderChild][com.squareup.workflow1.BaseRenderContext.renderChild].
  * @param output If non-null, [WorkflowOutput.value] will be "emitted" when this workflow is
  * rendered. The [WorkflowAction] used to handle this output can be verified using methods on
  * [RenderTestResult].
@@ -520,8 +520,8 @@ public inline fun <ChildPropsT, ChildOutputT, ChildRenderingT, PropsT, StateT, O
  * Specifies that this render pass is expected to run a particular side effect.
  *
  * @param key The key passed to
- * [runningSideEffect][com.squareup.workflow1.RenderContext.runningSideEffect] when rendering this
- * workflow.
+ * [runningSideEffect][com.squareup.workflow1.BaseRenderContext.runningSideEffect] when rendering
+ * this workflow.
  */
 public fun <PropsT, StateT, OutputT, RenderingT>
   RenderTester<PropsT, StateT, OutputT, RenderingT>.expectSideEffect(key: String):