Add kdocs on responsbilities of implementing SavedStateRegistryOwner
Details on how to properly implement SaveStateRegistryOwner and
how to call the SavedStateRegistryController methods
Test: n/a
Fixes: 228887344
Change-Id: Iefc9519241d9d6844868e6833b33081aa6908b7f
diff --git a/savedstate/savedstate/src/main/java/androidx/savedstate/SavedStateRegistryOwner.kt b/savedstate/savedstate/src/main/java/androidx/savedstate/SavedStateRegistryOwner.kt
index 6bb9586..dc63d7f 100644
--- a/savedstate/savedstate/src/main/java/androidx/savedstate/SavedStateRegistryOwner.kt
+++ b/savedstate/savedstate/src/main/java/androidx/savedstate/SavedStateRegistryOwner.kt
@@ -15,12 +15,33 @@
*/
package androidx.savedstate
+import androidx.lifecycle.Lifecycle
import androidx.lifecycle.LifecycleOwner
-
+import androidx.lifecycle.LifecycleObserver
/**
* A scope that owns [SavedStateRegistry]
*
- * @see ViewTreeSavedStateRegistryOwner
+ * This owner should be passed in to create a [SavedStateRegistryController] object
+ * through which this owner can access and perform operations via the
+ * controller's [SavedStateRegistry]
+ *
+ * [SavedStateRegistryController.performAttach] must be called once (and only once) on the
+ * main thread during the owner's [Lifecycle.State.INITIALIZED] state.
+ * It should be called before you call [SavedStateRegistryController.performRestore]
+ *
+ * [SavedStateRegistryController.performRestore] can be called with a nullable if nothing
+ * needs to be restored, or with the state Bundle to be restored. performRestore can be called
+ * in one of two places:
+ * 1. Directly before the Lifecycle moves to [Lifecycle.State.CREATED]
+ * 2. Before [Lifecycle.State.STARTED] is reached, as part of the [LifecycleObserver]
+ * that is added during owner initialization
+ *
+ * [SavedStateRegistryController.performSave] should be called after owner has been stopped but
+ * before it reaches [Lifecycle.State.DESTROYED] state. Hence it should only be called once the
+ * owner has received the [Lifecycle.Event.ON_STOP] event. The bundle passed to performSave
+ * will be the bundle restored by performRestore.
+ *
+ * @see [ViewTreeSavedStateRegistryOwner]
*/
interface SavedStateRegistryOwner : LifecycleOwner {
/**
