Punched up kdoc for AndroidScreen, ComposeScreen, ScreenComposableFac…

…tory

workflow-ui/compose/src/main/java/com/squareup/workflow1/ui/compose/ComposeScreen.kt

@@ -1,7 +1,6 @@
 package com.squareup.workflow1.ui.compose
 
 import androidx.compose.runtime.Composable
-import com.squareup.workflow1.ui.AndroidScreen
 import com.squareup.workflow1.ui.Screen
 import com.squareup.workflow1.ui.ViewEnvironment
 import com.squareup.workflow1.ui.ViewRegistry
@@ -10,7 +9,16 @@ import com.squareup.workflow1.ui.WorkflowUiExperimentalApi
 /**
  * Interface implemented by a rendering class to allow it to drive a composable UI via an
  * appropriate [ScreenComposableFactory] implementation, by simply overriding the [Content] method.
- * This is the compose analog to [AndroidScreen].
+ *
+ * Note that it is generally an error for a [Workflow][com.squareup.workflow1.Workflow]
+ * to declare [ComposeScreen] as its `RenderingT` type -- prefer [Screen] for that.
+ * [ComposeScreen], like [AndroidScreen][com.squareup.workflow1.ui.AndroidScreen],
+ * is strictly a possible implementation detail of [Screen]. It is a convenience to
+ * minimize the boilerplate required to set up a [ScreenComposableFactory].
+ * That interface is the fundamental unit of Compose tooling for Workflow UI.
+ * But in day to day use, most developer will work with [ComposeScreen] and be only
+ * vaguely aware of the existence of [ScreenComposableFactory],
+ * so the bulk of our description of working with Compose is here.
  *
  * **NB**: A Workflow app that relies on Compose must call [withComposeInteropSupport]
  * on its top-level [ViewEnvironment]. See that function for details.

workflow-ui/compose/src/main/java/com/squareup/workflow1/ui/compose/ScreenComposableFactory.kt

@@ -51,11 +51,13 @@ internal fun <ScreenT : Screen> ScreenComposableFactory(
 
 /**
  * A [ViewRegistry.Entry] that uses a [Composable] function to display [ScreenT].
- * This is the Compose-based analogue of
- * [ScreenViewFactory][com.squareup.workflow1.ui.ScreenViewFactory]. But unlike
- * [ScreenViewFactory], it is unusual for app developers to interact with this
- * class directly. Most of the time you can subclass [ComposeScreen] and rely on
- * the standard hidden [ScreenComposableFactory] that backs it.
+ * This is the fundamental unit of Compose tooling in Workflow UI, the Compose analogue of
+ * [ScreenViewFactory][com.squareup.workflow1.ui.ScreenViewFactory].
+ *
+ * [ScreenComposableFactory] is also a bit cumbersome to use directly,
+ * so [ComposeScreen] is provided as a convenience. Most developers will
+ * have no reason to work with [ScreenComposableFactory] directly, or even
+ * be aware of it.
  *
  * - See [ComposeScreen] for a more complete description of using Compose to
  *   build a Workflow-based UI.
@@ -78,7 +80,6 @@ internal fun <ScreenT : Screen> ScreenComposableFactory(
  *     renderWorkflowIn(
  *       workflow = MyWorkflow.mapRendering { it.withEnvironment(viewEnvironment) }
  *     )
- *
  */
 @WorkflowUiExperimentalApi
 public interface ScreenComposableFactory<in ScreenT : Screen> : ViewRegistry.Entry<ScreenT> {

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

@@ -1,8 +1,13 @@
 package com.squareup.workflow1.ui
 
 /**
- * Interface implemented by a rendering class to allow it to drive an Android UI
- * via an appropriate [ScreenViewFactory] implementation.
+ * Interface implemented by a [Screen] rendering class to minimize the boilerplate
+ * required for it to drive an Android UI via an appropriate [ScreenViewFactory]
+ * implementation.
+ *
+ * Note that it is generally an error for a [Workflow][com.squareup.workflow1.Workflow]
+ * to declare [AndroidScreen] as its `RenderingT` type -- prefer [Screen] for that.
+ * [AndroidScreen] is strictly a possible implementation detail of [Screen].
  *
  * You will rarely, if ever, write a [ScreenViewFactory] yourself. Use one
  * of its [companion methods][ScreenViewFactory.Companion] like [ScreenViewFactory.fromViewBinding]