Adds a lot more kdoc about Overlay and Dialog.

Author: rjrjr

workflow-ui/core-android/api/core-android.api

@@ -432,8 +432,6 @@ public class com/squareup/workflow1/ui/container/AlertOverlayDialogFactory : com
 	public fun buildDialog (Lcom/squareup/workflow1/ui/container/AlertOverlay;Lcom/squareup/workflow1/ui/ViewEnvironment;Landroid/content/Context;)Lcom/squareup/workflow1/ui/container/OverlayDialogHolder;
 	public synthetic fun buildDialog (Lcom/squareup/workflow1/ui/container/Overlay;Lcom/squareup/workflow1/ui/ViewEnvironment;Landroid/content/Context;)Lcom/squareup/workflow1/ui/container/OverlayDialogHolder;
 	public fun getType ()Lkotlin/reflect/KClass;
-	protected final fun toId (Lcom/squareup/workflow1/ui/container/AlertOverlay$Button;)I
-	protected final fun updateButtonsOnShow (Landroid/app/AlertDialog;Lcom/squareup/workflow1/ui/container/AlertOverlay;)V
 }
 
 public final class com/squareup/workflow1/ui/container/AndroidDialogBoundsKt {

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

@@ -25,13 +25,13 @@ import kotlin.reflect.KClass
 public open class AlertOverlayDialogFactory : OverlayDialogFactory<AlertOverlay> {
   override val type: KClass<AlertOverlay> = AlertOverlay::class
 
-  open override fun buildDialog(
+  override fun buildDialog(
     initialRendering: AlertOverlay,
     initialEnvironment: ViewEnvironment,
     context: Context
   ): OverlayDialogHolder<AlertOverlay> {
     return AlertDialog.Builder(context, initialEnvironment[AlertDialogThemeResId])
-      .create().apply {
+      .create().let { alertDialog ->
         for (button in Button.values()) {
           // We want to be able to update the alert while it's showing, including to maybe
           // show more buttons than were there originally. The API for Android's `AlertDialog`
@@ -41,18 +41,17 @@ public open class AlertOverlayDialogFactory : OverlayDialogFactory<AlertOverlay>
           //
           // We also don't want Android to tear down the dialog without our say so --
           // again, we might need to update the thing. But there is a dismiss call
-          // built in to click handers put in place by `AlertDialog`. So, when we're
+          // built in to click handlers put in place by `AlertDialog`. So, when we're
           // preflighting every possible button, we put garbage click handlers in place.
           // Then we replace them with our own, again at update time, by setting each live
           // button's click handler directly, without letting `AlertDialog` interfere.
           //
           // https://github.com/square/workflow-kotlin/issues/138
           //
           // Why " "? An empty string means no button.
-          setButton(button.toId(), " ") { _, _ -> }
+          alertDialog.setButton(button.toId(), " ") { _, _ -> }
         }
-      }
-      .let { alertDialog ->
+
         OverlayDialogHolder(initialEnvironment, alertDialog) { rendering, _ ->
           with(alertDialog) {
             if (rendering.cancelable) {
@@ -74,13 +73,13 @@ public open class AlertOverlayDialogFactory : OverlayDialogFactory<AlertOverlay>
       }
   }
 
-  protected fun Button.toId(): Int = when (this) {
+  private fun Button.toId(): Int = when (this) {
     POSITIVE -> DialogInterface.BUTTON_POSITIVE
     NEGATIVE -> DialogInterface.BUTTON_NEGATIVE
     NEUTRAL -> DialogInterface.BUTTON_NEUTRAL
   }
 
-  protected fun AlertDialog.updateButtonsOnShow(rendering: AlertOverlay) {
+  private fun AlertDialog.updateButtonsOnShow(rendering: AlertOverlay) {
     setOnShowListener(null)
 
     for (button in Button.values()) getButton(button.toId()).visibility = GONE

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

@@ -6,6 +6,15 @@ import com.squareup.workflow1.ui.WorkflowUiExperimentalApi
  * Interface implemented by a rendering class to allow it to drive an Android UI
  * via an appropriate [OverlayDialogFactory] implementation.
  *
+ * Note that you can mix this interface with others:
+ *
+ * - [ModalOverlay] to indicate that user input to covered views and dialogs
+ *   should be blocked while this one is visible.
+ *
+ * - [ScreenOverlay] for dialogs whose content is defined by a wrapped
+ *   [Screen][com.squareup.workflow1.ui.Screen] instance. And in this case,
+ *   also note [ScreenOverlayDialogFactory].
+ *
  * This is the simplest way to introduce a [Dialog][android.app.Dialog] workflow driven UI,
  * but using it requires your workflows code to reside in Android modules, instead
  * of pure Kotlin. If this is a problem, or you need more flexibility for any other

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

@@ -19,6 +19,16 @@ import com.squareup.workflow1.ui.ViewEnvironment
 import com.squareup.workflow1.ui.WorkflowUiExperimentalApi
 import com.squareup.workflow1.ui.WorkflowViewStub
 
+/**
+ * Default container for [Overlay] renderings, providing support for
+ * orthogonal subtypes [ModalOverlay] and [ScreenOverlay]. As much
+ * work as possible is delegated to the public [LayeredDialogSessions]
+ * support class, to make it practical to write custom forks should
+ * the need arise.
+ *
+ * See [ScreenOverlayDialogFactory] for a general overview of how
+ * Workflow's [android.app.Dialog] support actually works.
+ */
 @WorkflowUiExperimentalApi
 internal class BodyAndOverlaysContainer @JvmOverloads constructor(
   context: Context,

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

@@ -18,7 +18,8 @@ import com.squareup.workflow1.ui.androidx.WorkflowSavedStateRegistryAggregator
 
 /**
  * Used by [LayeredDialogSessions] to manage lifecycle and view persistence concerns for an
- * [OverlayDialogHolder], as well as enforcing modal behavior.
+ * [OverlayDialogHolder], as well as enforcing modal behavior. See [LayeredDialogSessions]
+ * for a general overview of the lifecycle of a managed [Dialog][android.app.Dialog].
  */
 @WorkflowUiExperimentalApi
 internal class DialogSession(

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

@@ -24,8 +24,50 @@ import kotlinx.coroutines.flow.StateFlow
 /**
  * Does the bulk of the work of maintaining a set of [Dialog][android.app.Dialog]s
  * to reflect lists of [Overlay]. Can be used to create custom [Overlay]-based
- * layouts if [BodyAndOverlaysScreen] or the default [View] bound to it are too restrictive.
- * Provides a [LifecycleOwner] per managed dialog, and view persistence support.
+ * layouts if [BodyAndOverlaysScreen] or the default [BodyAndOverlaysContainer] bound
+ * to it are too restrictive.
+ *
+ * Provides an [allowEvents] field that reflects the presence or absence of Dialogs driven
+ * by [ModalOverlay], and makes [OverlayArea] available in the [ViewEnvironment],
+ * which in turn drives calls to [ScreenOverlayDialogFactory.updateBounds].
+ *
+ * Provides a [ViewTreeLifecycleOwner] per managed Dialog, and view persistence support,
+ * both for classic [View.onSaveInstanceState] and
+ * Jetpack [SavedStateRegistry][androidx.savedstate.SavedStateRegistry].
+ *
+ * ## Lifecycle of a managed [Dialog][android.app.Dialog]
+ *
+ * When [update] is called with an [Overlay] that is not [Compatible] with an
+ * existing Dialog at the same index, the appropriate [OverlayDialogFactory] instance
+ * is fetched from the [ViewEnvironment]. That factory builds (but does not
+ * [show][android.app.Dialog.show]) a new Dialog, wrapped in an [OverlayDialogHolder].
+ * The holder in turn is held by a [DialogSession] instance. There is a 1:1:1 relationship
+ * between the Dialog, the [OverlayDialogHolder] which can [update it][OverlayDialogHolder.show],
+ * and the [DialogSession] that manages its [LifecycleOwner] and persistence.
+ *
+ * When a new [DialogSession] begins:
+ *
+ * - a [ViewTreeLifecycleOwner] is created as a child to the one provided
+ *   by [getParentLifecycleOwner]
+ *
+ * - An appropriately scoped [SavedStateRegistry][androidx.savedstate.SavedStateRegistry]
+ *   is put in place, provided that [onAttachedToWindow] and [onDetachedFromWindow] are
+ *   called from the like named methods of the nearest container View
+ *
+ * - Any available classic View state is restored to the new Dialog's content View tree,
+ *   provided that [onSaveInstanceState] and [onRestoreInstanceState] are called from the
+ *   like named methods of that container View
+ *
+ * - And the Dialog is [shown][android.app.Dialog.show]
+ *
+ * The [DialogSession] is maintained (and its two flavors of View state are recorded
+ * as prompted by the Android runtime) so long as [update] is called with a
+ * [Compatible] [Overlay] rendering in the same position.
+ *
+ * When [update] is called without a matching [Overlay], or the
+ * [parent Lifecycle][getParentLifecycleOwner] ends, the [DialogSession] ends,
+ * its [ViewTreeLifecycleOwner] is destroyed, and the Dialog is
+ * [dismissed][android.app.Dialog.dismiss].
  *
  * @param bounds made available to managed dialogs via the [OverlayArea]
  * [ViewEnvironmentKey][com.squareup.workflow1.ui.ViewEnvironmentKey],
@@ -37,7 +79,6 @@ import kotlinx.coroutines.flow.StateFlow
  *
  * @param getParentLifecycleOwner provides the [LifecycleOwner] to serve as
  * an ancestor to those created for managed [Dialog][android.app.Dialog]s.
- *
  */
 @WorkflowUiExperimentalApi
 public class LayeredDialogSessions private constructor(

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

@@ -9,9 +9,17 @@ import com.squareup.workflow1.ui.WorkflowUiExperimentalApi
 /**
  * Factory for [Dialog] instances that can show renderings of type [OverlayT] : [Overlay].
  *
- * It's simplest to have your rendering classes implement [AndroidOverlay] to associate
+ * Implement this interface directly for rendering types that are completely self-descriptive,
+ * like [AlertOverlay]. For dialogs that wrap a [Screen][com.squareup.workflow1.ui.Screen]
+ * for their content, implement [ScreenOverlayDialogFactory] interface and use the
+ * [ScreenOverlay] rendering type.
+ *
+ * To minimize boilerplate, have your rendering classes implement [AndroidOverlay] to associate
  * them with appropriate an appropriate [OverlayDialogFactory]. For more flexibility, and to
  * avoid coupling your workflow directly to the Android runtime, see [ViewRegistry].
+ *
+ * See the kdoc on [ScreenOverlayDialogFactory] for a fuller description of how
+ * [Dialog]s are placed on the screen, and their impact on UI events.
  */
 @WorkflowUiExperimentalApi
 public interface OverlayDialogFactory<OverlayT : Overlay> : ViewRegistry.Entry<OverlayT> {

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

@@ -8,14 +8,14 @@ import com.squareup.workflow1.ui.WorkflowUiExperimentalApi
 internal class RealOverlayDialogHolder<OverlayT : Overlay>(
   initialEnvironment: ViewEnvironment,
   override val dialog: Dialog,
-  runner: (rendering: OverlayT, environment: ViewEnvironment) -> Unit
+  runnerFunction: (rendering: OverlayT, environment: ViewEnvironment) -> Unit
 ) : OverlayDialogHolder<OverlayT> {
 
   private var _environment: ViewEnvironment = initialEnvironment
   override val environment: ViewEnvironment get() = _environment
 
   override val runner = { newScreen: OverlayT, newEnvironment: ViewEnvironment ->
     _environment = newEnvironment
-    runner(newScreen, newEnvironment)
+    runnerFunction(newScreen, newEnvironment)
   }
 }

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

@@ -33,12 +33,11 @@ import kotlin.reflect.KClass
  * and honor the [OverlayArea] and [CoveredByModal] values placed in
  * the [ViewEnvironment] by the standard [BodyAndOverlaysScreen] container.
  *
- * ## Implementation notes
+ * ## Details of [Dialog] management
  *
- * Our Android dialog management story is complex. There is a lot of machinery in play to
- * to provide control over the placement of dialog windows, and to ensure that modal
- * dialogs behave as expected -- e.g., that events in the Activity window are blocked
- * the instant a modal dialog is shown.
+ * There is a lot of machinery in play to to provide control over the placement of
+ * [Dialog] windows, and to ensure that [ModalOverlay] dialogs behave as expected (i.e.,
+ * that events in the Activity window are blocked the instant a modal [Dialog] is shown).
  *
  * For placement, consider a layout where we want the option to show a tutorial bar below
  * the main UI.

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

@@ -9,8 +9,12 @@ import com.squareup.workflow1.ui.WorkflowUiExperimentalApi
  * An Overlay can be any part of the UI that visually floats in a layer above the main UI,
  * or above other Overlays. Possible examples include alerts, drawers, and tooltips.
  *
- * Note in particular that an Overlay is not necessarily a modal window.
+ * Note in particular that an Overlay is not necessarily a modal window -- that is,
+ * one that prevents covered views and windows from processing UI events.
  * Rendering types can opt into modality by extending [ModalOverlay].
+ *
+ * See [ScreenOverlay] to define an [Overlay] whose content is provided by a wrapped
+ * [Screen][com.squareup.workflow1.ui.Screen].
  */
 @WorkflowUiExperimentalApi
 public interface Overlay