More kdoc

Author: rjrjr

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

@@ -27,6 +27,8 @@ package com.squareup.workflow1.ui
  * reason, you can use [ViewRegistry] to bind your renderings to [ScreenViewFactory]
  * implementations at runtime. Also note that a [ViewRegistry] entry will override
  * the [viewFactory] returned by an [AndroidScreen].
+ *
+ * @see com.squareup.workflow1.ui.container.AndroidOverlay
  */
 @WorkflowUiExperimentalApi
 public interface AndroidScreen<S : AndroidScreen<S>> : Screen {

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

@@ -2,7 +2,21 @@ package com.squareup.workflow1.ui.container
 
 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.
+ *
+ * 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
+ * reason, you can use [ViewRegistry][com.squareup.workflow1.ui.ViewRegistry] to bind
+ * your renderings to [OverlayDialogFactory] implementations at runtime.
+ * Also note that a `ViewRegistry` entry will override the [dialogFactory] returned by
+ * an [AndroidOverlay].
+ *
+ * @see com.squareup.workflow1.ui.AndroidScreen
+ */
 @WorkflowUiExperimentalApi
-public interface AndroidOverlay<O: AndroidOverlay<O>> : Overlay {
+public interface AndroidOverlay<O : AndroidOverlay<O>> : Overlay {
   public val dialogFactory: OverlayDialogFactory<O>
 }

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

@@ -12,24 +12,42 @@ import com.squareup.workflow1.ui.androidx.WorkflowLifecycleOwner
 import com.squareup.workflow1.ui.container.DialogRunner.KeyAndBundle
 
 /**
- * Does the work of maintaining a set of [Dialog][android.app.Dialog]s
- * to reflect lists of [Overlay].
+ * 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 [BodyAndModalsScreen] or the default [View] bound to it are too restrictive.
+ * Provides a [LifecycleOwner] per managed dialog, and view persistence support.
  */
 @WorkflowUiExperimentalApi
 public class DialogStack(
   private val context: Context,
   private val getParentLifecycleOwner: () -> LifecycleOwner?,
   private val createRectProvider: (Overlay) -> RectProvider
 ) {
+  /**
+   * Builds a [DialogStack] whose overlays' [bounds][createRectProvider] track those
+   * of [view], and which looks through [view] to find their
+   * [LifecycleOwner][getParentLifecycleOwner].
+   */
   public constructor(
     view: View,
     createRectProvider: (Overlay) -> RectProvider = { ViewRectProvider(view) }
   ) : this(view.context, { WorkflowLifecycleOwner.get(view) }, createRectProvider)
 
   private var runners: List<DialogRunner<*>> = emptyList()
 
+  /** True when any dialogs are visible, or becoming visible. */
   public val hasDialogs: Boolean = runners.isNotEmpty()
 
+  /**
+   * Updates the managed set of [Dialog][android.app.Dialog] instances to reflect
+   * [overlays]. Opens new dialogs, updates existing ones, and dismisses those
+   * that match no member of that list.
+   *
+   * Each dialog has its own [WorkflowLifecycleOwner], which starts when the dialog
+   * is shown, and is destroyed when it is dismissed. Views nested in a managed dialog
+   * can use [ViewTreeLifecycleOwner][androidx.lifecycle.ViewTreeLifecycleOwner] as
+   * usual.
+   */
   public fun update(
     overlays: List<Overlay>,
     viewEnvironment: ViewEnvironment,
@@ -62,10 +80,12 @@ public class DialogStack(
     // TODO Smarter diffing, and Z order. Maybe just hide and show everything on every update?
   }
 
+  /** To be called from a container view's [View.onSaveInstanceState]. */
   public fun onSaveInstanceState(): SavedState {
     return SavedState(runners.mapNotNull { it.save() })
   }
 
+  /** To be called from a container view's [View.onRestoreInstanceState]. */
   public fun onRestoreInstanceState(state: SavedState) {
     if (state.dialogBundles.size == runners.size) {
       state.dialogBundles.zip(runners) { viewState, runner -> runner.restore(viewState) }

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

@@ -6,14 +6,21 @@ import com.squareup.workflow1.ui.ViewEnvironment
 import com.squareup.workflow1.ui.ViewRegistry
 import com.squareup.workflow1.ui.WorkflowUiExperimentalApi
 
+/**
+ * Factory for [Dialog] instances that can show renderings of type [RenderingT] : [Overlay].
+ *
+ * It's simplest to 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].
+ */
 @WorkflowUiExperimentalApi
-public interface OverlayDialogFactory<T : Overlay> : ViewRegistry.Entry<T> {
+public interface OverlayDialogFactory<RenderingT : Overlay> : ViewRegistry.Entry<RenderingT> {
   /**
    * Build a [Dialog], typically using [bounds] to set and maintain its bounds.
    * Do not show it.
    */
   public fun buildDialog(
-    initialRendering: T,
+    initialRendering: RenderingT,
     initialEnvironment: ViewEnvironment,
     bounds: RectProvider,
     context: Context
@@ -26,7 +33,7 @@ public interface OverlayDialogFactory<T : Overlay> : ViewRegistry.Entry<T> {
    */
   public fun updateDialog(
     dialog: Dialog,
-    rendering: T,
+    rendering: RenderingT,
     environment: ViewEnvironment
   )
 }

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

@@ -3,10 +3,26 @@ package com.squareup.workflow1.ui.container
 import android.graphics.Rect
 import android.view.View
 
+/**
+ * Defines the desired bounds for a [Dialog][android.app.Dialog] built by
+ * [OverlayDialogFactory.buildDialog]. Custom containers can define their
+ * bounds policy via [DialogStack.createRectProvider].
+ *
+ * Use [ViewRectProvider] to monitor the bounds of a [View].
+ */
 public interface RectProvider {
+  /**
+   * Called once the bounds are known, and each time they change.
+   * May be called immediately.
+   */
   public var onChange: ((Rect) -> Unit)?
 }
 
+/**
+ * A [RectProvider] that reports the bounds of the given [view], starting when it is
+ * first attached, and ceasing when it is first detached. [RectProvider.onChange] is
+ * called immediately if [view] is already attached.
+ */
 public class ViewRectProvider(
   public val view: View
 ) : RectProvider {