Renames Workflow.run() to take(), improves kdoc.

Author: rjrjr

samples/hello-workflow-fragment/src/main/java/com/squareup/sample/helloworkflowfragment/HelloWorkflowFragment.kt

@@ -26,7 +26,7 @@ class HelloWorkflowFragment : Fragment() {
     val model: HelloViewModel = ViewModelProvider(this).get(HelloViewModel::class.java)
 
     return WorkflowLayout(inflater.context).apply {
-      run(model.renderings)
+      take(model.renderings)
     }
   }
 }

samples/hello-workflow/src/main/java/com/squareup/sample/helloworkflow/HelloWorkflowActivity.kt

@@ -21,7 +21,7 @@ class HelloWorkflowActivity : AppCompatActivity() {
     // succeeding calls.
     val model: HelloViewModel by viewModels()
     setContentView(
-      WorkflowLayout(this).apply { run(model.renderings) }
+      WorkflowLayout(this).apply { take(model.renderings) }
     )
   }
 }

samples/stub-visibility/src/main/java/com/squareup/sample/stubvisibility/StubVisibilityActivity.kt

@@ -20,7 +20,7 @@ class StubVisibilityActivity : AppCompatActivity() {
 
     val model: StubVisibilityModel by viewModels()
     setContentView(
-      WorkflowLayout(this).apply { run(model.renderings) }
+      WorkflowLayout(this).apply { take(model.renderings) }
     )
   }
 }

workflow-ui/core-android/src/main/java/com/squareup/workflow1/ui/WorkflowLayout.kt

@@ -48,29 +48,48 @@ public class WorkflowLayout(
   private var restoredChildState: SparseArray<Parcelable>? = null
 
   /**
-   * Subscribes to [renderings], and uses a [WorkflowLayout] to display its values.
+   * Subscribes to [renderings] and display its values.
+   *
    * To configure the [ViewEnvironment], e.g. to customize the UI via [ViewRegistry] entries,
-   * use [RootScreen] as your rendering type.
+   * use [RootScreen] as your rendering type. e.g.
+   *
+   *     val registry = ViewRegistry(MuchBetterViewForFooScreen)
+   *     val env = ViewEnvironment(mapOf(ViewRegistry to registry))
+   *     val renderings = renderWorkflowIn(...).map { RootScreen(it, env) }
+   *     workflowLayout.take(renderings)
    */
-  public fun run(renderings: Flow<Screen>) {
+  public fun take(renderings: Flow<Screen>) {
     takeWhileAttached(renderings.map { it.asRoot() }) { show(it) }
   }
 
-  @Suppress("DEPRECATION")
-  @Deprecated("Use run()", ReplaceWith("go(renderings)"))
+  @Deprecated(
+    "Use take()",
+    ReplaceWith(
+      "take(renderings.map { " +
+        "RootScreen(asScreen(it), ViewEnvironment(mapOf(ViewRegistry to registry))) " +
+        "})",
+      "com.squareup.workflow1.ui.AsScreen.Companion.asScreen",
+      "com.squareup.workflow1.ui.ViewEnvironment",
+      "com.squareup.workflow1.ui.ViewRegistry",
+      "com.squareup.workflow1.ui.container.RootScreen",
+      "kotlinx.coroutines.flow.map"
+    )
+  )
   public fun start(
     renderings: Flow<Any>,
     registry: ViewRegistry
   ) {
+    @Suppress("DEPRECATION")
     start(renderings, ViewEnvironment(mapOf(ViewRegistry to registry)))
   }
 
-  @Deprecated("Use run()", ReplaceWith("run(renderings)"))
+  @Deprecated("Use take()", ReplaceWith("take(renderings)"))
   public fun start(
     renderings: Flow<Any>,
     environment: ViewEnvironment = ViewEnvironment()
   ) {
     takeWhileAttached(renderings) {
+      @Suppress("DEPRECATION")
       show(AsScreen.asScreen(it).asRoot() + environment)
     }
   }

workflow-ui/core-common/src/main/java/com/squareup/workflow1/ui/AsScreen.kt

@@ -1,5 +1,12 @@
+@file:Suppress("DEPRECATION")
+
 package com.squareup.workflow1.ui
 
+/**
+ * Provides backward compatibility for non-[Screen] renderings based on
+ * `ViewFactory` and `AndroidViewRendering`.
+ */
+@Deprecated("Implement Screen directly.")
 @WorkflowUiExperimentalApi
 public class AsScreen<W : Any>(
   public val rendering: W
@@ -15,8 +22,9 @@ public class AsScreen<W : Any>(
 
   public companion object {
     /**
-     * Transforms [rendering] to implement [Screen], wrapping it in an [AsScreen] if necessary.
+     * Ensures [rendering] implements [Screen], wrapping it in an [AsScreen] if necessary.
      */
+    @Deprecated("Implement Screen directly.")
     public fun asScreen(rendering: Any): Screen {
       return when (rendering) {
         is Screen -> rendering