From c7fa2c3de670f4bb7e431853e239dd7d1f4aa7bb Mon Sep 17 00:00:00 2001
From: jbibik <jbibik@google.com>
Date: Thu, 27 Feb 2025 05:19:55 -0800
Subject: [PATCH] [ui-compose] Add KDoc to observe() methods for button states

#cherrypick

PiperOrigin-RevId: 731686021
(cherry picked from commit b465cbc22c61acc07875550d1c1f24aa5d080f13)
---
 .../androidx/media3/ui/compose/state/NextButtonState.kt    | 5 +++++
 .../androidx/media3/ui/compose/state/PresentationState.kt  | 6 ++++++
 .../media3/ui/compose/state/PreviousButtonState.kt         | 5 +++++
 .../androidx/media3/ui/compose/state/RepeatButtonState.kt  | 6 ++++++
 .../androidx/media3/ui/compose/state/ShuffleButtonState.kt | 7 +++++++
 5 files changed, 29 insertions(+)

diff --git a/libraries/ui_compose/src/main/java/androidx/media3/ui/compose/state/NextButtonState.kt b/libraries/ui_compose/src/main/java/androidx/media3/ui/compose/state/NextButtonState.kt
index 0e489f44d8..a66436c22b 100644
--- a/libraries/ui_compose/src/main/java/androidx/media3/ui/compose/state/NextButtonState.kt
+++ b/libraries/ui_compose/src/main/java/androidx/media3/ui/compose/state/NextButtonState.kt
@@ -56,6 +56,11 @@ class NextButtonState(private val player: Player) {
     player.seekToNext()
   }
 
+  /**
+   * Subscribes to updates from [Player.Events] and listens to
+   * [Player.EVENT_AVAILABLE_COMMANDS_CHANGED] in order to determine whether the button should be
+   * enabled, i.e. respond to user input.
+   */
   suspend fun observe(): Nothing =
     player.listen { events ->
       if (events.contains(Player.EVENT_AVAILABLE_COMMANDS_CHANGED)) {
diff --git a/libraries/ui_compose/src/main/java/androidx/media3/ui/compose/state/PresentationState.kt b/libraries/ui_compose/src/main/java/androidx/media3/ui/compose/state/PresentationState.kt
index 89c72d1d34..c94f6d625d 100644
--- a/libraries/ui_compose/src/main/java/androidx/media3/ui/compose/state/PresentationState.kt
+++ b/libraries/ui_compose/src/main/java/androidx/media3/ui/compose/state/PresentationState.kt
@@ -79,6 +79,12 @@ class PresentationState(private val player: Player) {
 
   private var lastPeriodUidWithTracks: Any? = null
 
+  /**
+   * Subscribes to updates from [Player.Events] and listens to
+   * * [Player.EVENT_VIDEO_SIZE_CHANGED] to determine pixelWidthHeightRatio-adjusted video size
+   * * [Player.EVENT_RENDERED_FIRST_FRAME] and [Player.EVENT_TRACKS_CHANGED]to determine whether the
+   *   surface is ready to be shown
+   */
   suspend fun observe(): Nothing =
     player.listen { events ->
       if (events.contains(Player.EVENT_VIDEO_SIZE_CHANGED)) {
diff --git a/libraries/ui_compose/src/main/java/androidx/media3/ui/compose/state/PreviousButtonState.kt b/libraries/ui_compose/src/main/java/androidx/media3/ui/compose/state/PreviousButtonState.kt
index 2037def75f..9e50290b62 100644
--- a/libraries/ui_compose/src/main/java/androidx/media3/ui/compose/state/PreviousButtonState.kt
+++ b/libraries/ui_compose/src/main/java/androidx/media3/ui/compose/state/PreviousButtonState.kt
@@ -56,6 +56,11 @@ class PreviousButtonState(private val player: Player) {
     player.seekToPrevious()
   }
 
+  /**
+   * Subscribes to updates from [Player.Events] and listens to
+   * [Player.EVENT_AVAILABLE_COMMANDS_CHANGED] in order to determine whether the button should be
+   * enabled, i.e. respond to user input.
+   */
   suspend fun observe(): Nothing =
     player.listen { events ->
       if (events.contains(Player.EVENT_AVAILABLE_COMMANDS_CHANGED)) {
diff --git a/libraries/ui_compose/src/main/java/androidx/media3/ui/compose/state/RepeatButtonState.kt b/libraries/ui_compose/src/main/java/androidx/media3/ui/compose/state/RepeatButtonState.kt
index 439d161d0d..72f6e07700 100644
--- a/libraries/ui_compose/src/main/java/androidx/media3/ui/compose/state/RepeatButtonState.kt
+++ b/libraries/ui_compose/src/main/java/androidx/media3/ui/compose/state/RepeatButtonState.kt
@@ -80,6 +80,12 @@ class RepeatButtonState(
     player.repeatMode = getNextRepeatModeInSequence()
   }
 
+  /**
+   * Subscribes to updates from [Player.Events] and listens to
+   * * [Player.EVENT_REPEAT_MODE_CHANGED] in order to determine the latest [Player.getRepeatMode].
+   * * [Player.EVENT_AVAILABLE_COMMANDS_CHANGED] in order to determine whether the button should be
+   *   enabled, i.e. respond to user input.
+   */
   suspend fun observe(): Nothing =
     player.listen { events ->
       if (
diff --git a/libraries/ui_compose/src/main/java/androidx/media3/ui/compose/state/ShuffleButtonState.kt b/libraries/ui_compose/src/main/java/androidx/media3/ui/compose/state/ShuffleButtonState.kt
index 6a5bab515a..2ff3ef3829 100644
--- a/libraries/ui_compose/src/main/java/androidx/media3/ui/compose/state/ShuffleButtonState.kt
+++ b/libraries/ui_compose/src/main/java/androidx/media3/ui/compose/state/ShuffleButtonState.kt
@@ -58,6 +58,13 @@ class ShuffleButtonState(private val player: Player) {
     player.shuffleModeEnabled = !player.shuffleModeEnabled
   }
 
+  /**
+   * Subscribes to updates from [Player.Events] and listens to
+   * * [Player.EVENT_SHUFFLE_MODE_ENABLED_CHANGED] in order to determine the latest
+   *   [Player.getShuffleModeEnabled].
+   * * [Player.EVENT_AVAILABLE_COMMANDS_CHANGED] in order to determine whether the button should be
+   *   enabled, i.e. respond to user input.
+   */
   suspend fun observe(): Nothing =
     player.listen { events ->
       if (