From 064526dbcf18cb27190536ee1125a9af97916cd6 Mon Sep 17 00:00:00 2001
From: David Jia <davidjia@google.com>
Date: Fri, 6 Feb 2026 11:29:53 -0800
Subject: [PATCH 1/3] Kdocs for ui/uistateadapter/capture

---
 .../capture/AspectRatioUiStateAdapter.kt      |  9 ++++++
 .../capture/AudioUiStateAdapter.kt            |  7 ++++
 .../capture/CaptureButtonUiStateAdapter.kt    | 15 +++++++++
 .../capture/CaptureModeUiStateAdapter.kt      | 28 ++++++++++++++++
 .../capture/ConcurrentCameraUiStateAdapter.kt | 22 +++++++++++++
 .../capture/DebugUiStateAdapter.kt            | 32 +++++++++++++++++++
 .../capture/ElapsedTimeUiStateAdapter.kt      | 15 +++++++++
 .../capture/FlashModeUiStateAdapter.kt        | 28 ++++++++++++++++
 .../capture/FlipLensUiStateAdapter.kt         | 14 ++++++++
 .../capture/FocusMeteringUiStateAdapter.kt    | 24 ++++++++++++++
 .../capture/HdrUiStateAdapter.kt              | 24 ++++++++++++++
 .../capture/ImageWellUiStateAdapter.kt        | 13 ++++++++
 .../ui/uistateadapter/capture/PreviewMode.kt  | 23 -------------
 .../capture/StabilizationUiStateAdapter.kt    | 26 +++++++++++++++
 .../capture/StreamConfigsUiStateAdapter.kt    | 18 +++++++++++
 .../capture/ZoomControlUiStateAdapter.kt      | 23 +++++++++++++
 .../capture/ZoomUiStateAdapter.kt             | 15 +++++++++
 17 files changed, 313 insertions(+), 23 deletions(-)
 delete mode 100644 ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/PreviewMode.kt

diff --git a/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/AspectRatioUiStateAdapter.kt b/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/AspectRatioUiStateAdapter.kt
index b6811e36e..ff6c97763 100644
--- a/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/AspectRatioUiStateAdapter.kt
+++ b/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/AspectRatioUiStateAdapter.kt
@@ -26,6 +26,15 @@ private val ORDERED_UI_SUPPORTED_ASPECT_RATIOS = listOf(
     AspectRatio.ONE_ONE
 )
 
+/**
+ * Creates an [AspectRatioUiState] from [CameraAppSettings].
+ *
+ * @param cameraAppSettings The current camera application settings.
+ *
+ * @return An [AspectRatioUiState] representing the available aspect ratios and the currently
+ * selected one. If only one or no aspect ratios are supported, it returns
+ * [AspectRatioUiState.Unavailable].
+ */
 fun AspectRatioUiState.Companion.from(cameraAppSettings: CameraAppSettings): AspectRatioUiState {
     val supportedAspectRatios = ORDERED_UI_SUPPORTED_ASPECT_RATIOS.toSet()
     val availableAspectRatios =
diff --git a/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/AudioUiStateAdapter.kt b/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/AudioUiStateAdapter.kt
index 57fc83814..32e81431c 100644
--- a/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/AudioUiStateAdapter.kt
+++ b/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/AudioUiStateAdapter.kt
@@ -20,6 +20,13 @@ import com.google.jetpackcamera.core.camera.VideoRecordingState
 import com.google.jetpackcamera.settings.model.CameraAppSettings
 import com.google.jetpackcamera.ui.uistate.capture.AudioUiState
 
+/**
+ * Creates an [AudioUiState] from the given camera application settings.
+ *
+ * @param cameraAppSettings The current settings of the camera application.
+ * @return [AudioUiState.Enabled] if audio is enabled in the settings, otherwise
+ * [AudioUiState.Disabled].
+ */
 fun AudioUiState.Companion.from(
     cameraAppSettings: CameraAppSettings,
     cameraState: CameraState
diff --git a/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/CaptureButtonUiStateAdapter.kt b/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/CaptureButtonUiStateAdapter.kt
index e8e11a7ab..4f35f4323 100644
--- a/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/CaptureButtonUiStateAdapter.kt
+++ b/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/CaptureButtonUiStateAdapter.kt
@@ -20,6 +20,21 @@ import com.google.jetpackcamera.core.camera.VideoRecordingState
 import com.google.jetpackcamera.settings.model.CameraAppSettings
 import com.google.jetpackcamera.ui.uistate.capture.CaptureButtonUiState
 
+/**
+ * Creates a [CaptureButtonUiState] based on the current camera settings and state.
+ *
+ * This function determines the appropriate UI state for the main capture button, which can change
+ * depending on the current capture mode, video recording status, and whether the recording is locked.
+ *
+ * @param cameraAppSettings The current application settings, used to determine the capture mode.
+ * @param cameraState The current state of the camera, used to check video recording status.
+ * @param lockedState A boolean indicating whether the video recording is currently in a locked state.
+ *
+ * @return A [CaptureButtonUiState] representing the current state of the capture button.
+ *         - [CaptureButtonUiState.Enabled.Idle] if not recording.
+ *         - [CaptureButtonUiState.Enabled.Recording.PressedRecording] if recording is active but not locked.
+ *         - [CaptureButtonUiState.Enabled.Recording.LockedRecording] if recording is active and locked.
+ */
 fun CaptureButtonUiState.Companion.from(
     cameraAppSettings: CameraAppSettings,
     cameraState: CameraState,
diff --git a/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/CaptureModeUiStateAdapter.kt b/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/CaptureModeUiStateAdapter.kt
index 3fc563a03..11642f18e 100644
--- a/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/CaptureModeUiStateAdapter.kt
+++ b/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/CaptureModeUiStateAdapter.kt
@@ -39,6 +39,21 @@ private val ORDERED_UI_SUPPORTED_CAPTURE_MODES = listOf(
     CaptureMode.VIDEO_ONLY
 )
 
+/**
+ * Creates a [CaptureModeToggleUiState] based on the current camera and system state.
+ *
+ * This adapter determines whether the simplified capture mode toggle (between IMAGE_ONLY and
+ * VIDEO_ONLY) should be available and what its state should be. The toggle is generally
+ * unavailable if video is recording or if the current capture mode is STANDARD.
+ *
+ * @param systemConstraints The constraints of the entire camera system.
+ * @param cameraAppSettings The current settings of the camera.
+ * @param cameraState The real-time state of the camera hardware.
+ * @param externalCaptureMode The mode influencing UI based on how the camera was launched.
+ * @return A [CaptureModeToggleUiState] which is either [CaptureModeToggleUiState.Available]
+ * containing the states for the image and video-only modes, or
+ * [CaptureModeToggleUiState.Unavailable] if the toggle should not be shown.
+ */
 fun CaptureModeToggleUiState.Companion.from(
     systemConstraints: CameraSystemConstraints,
     cameraAppSettings: CameraAppSettings,
@@ -75,6 +90,19 @@ fun CaptureModeToggleUiState.Companion.from(
         )
     }
 
+/**
+ * Creates a [CaptureModeUiState] for the full capture mode selection UI (e.g., in quick settings).
+ *
+ * This adapter is responsible for determining the list of all available and selectable capture
+ * modes ([CaptureMode.STANDARD], [CaptureMode.IMAGE_ONLY], [CaptureMode.VIDEO_ONLY]) based on the
+ * current system and camera constraints.
+ *
+ * @param systemConstraints The constraints of the entire camera system.
+ * @param cameraAppSettings The current settings of the camera.
+ * @param externalCaptureMode The mode influencing UI based on how the camera was launched.
+ * @return A [CaptureModeUiState.Available] object containing the currently selected capture mode
+ * and a list of all available modes, each represented as a [SingleSelectableUiState].
+ */
 fun CaptureModeUiState.Companion.from(
     systemConstraints: CameraSystemConstraints,
     cameraAppSettings: CameraAppSettings,
diff --git a/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/ConcurrentCameraUiStateAdapter.kt b/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/ConcurrentCameraUiStateAdapter.kt
index 988012cef..df5addfaf 100644
--- a/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/ConcurrentCameraUiStateAdapter.kt
+++ b/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/ConcurrentCameraUiStateAdapter.kt
@@ -27,6 +27,28 @@ import com.google.jetpackcamera.ui.uistate.capture.CaptureModeUiState
 import com.google.jetpackcamera.ui.uistate.capture.ConcurrentCameraUiState
 import com.google.jetpackcamera.ui.uistate.capture.StreamConfigUiState
 
+/**
+ * Creates a [ConcurrentCameraUiState] based on the current camera and system state.
+ *
+ * This function determines the availability and current selection of the concurrent camera feature.
+ * It synthesizes various states and settings to decide if the concurrent camera mode can be
+ * enabled. The feature is considered disabled if any of the following conditions are true:
+ * - The device hardware does not support concurrent cameras.
+ * - The camera was launched with an external intent for single image capture.
+ * - The selected capture mode is exclusively for single image capture (`IMAGE_ONLY`).
+ * - An HDR mode (either HLG10 for video or ULTRA_HDR for images) is active.
+ * - The stream configuration is set to `SINGLE_STREAM`.
+ * - Low Light Boost flash mode is active.
+ *
+ * @param cameraAppSettings The current application-level camera settings.
+ * @param systemConstraints The capabilities and limitations of the device's camera hardware.
+ * @param externalCaptureMode The mode indicating if the camera was launched by an external intent.
+ * @param captureModeUiState The current state of the capture mode selection UI.
+ * @param streamConfigUiState The current state of the stream configuration UI.
+ * @return A [ConcurrentCameraUiState.Available] object containing the currently selected
+ * concurrent camera mode and a boolean indicating if the feature is currently enabled and
+ * can be interacted with.
+ */
 fun ConcurrentCameraUiState.Companion.from(
     cameraAppSettings: CameraAppSettings,
     systemConstraints: CameraSystemConstraints,
diff --git a/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/DebugUiStateAdapter.kt b/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/DebugUiStateAdapter.kt
index 0af3f3cb1..a65b59844 100644
--- a/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/DebugUiStateAdapter.kt
+++ b/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/DebugUiStateAdapter.kt
@@ -24,6 +24,24 @@ import com.google.jetpackcamera.settings.model.CameraSystemConstraints
 import com.google.jetpackcamera.settings.model.forCurrentLens
 import com.google.jetpackcamera.ui.uistate.capture.DebugUiState
 
+/**
+ * Creates a [DebugUiState.Enabled.Open] state from various camera and application sources.
+ *
+ * This function is responsible for gathering all necessary information to populate the fully
+ * expanded debug UI overlay. It combines system capabilities, current settings, and real-time
+ * camera state into a comprehensive UI state object.
+ *
+ * @param systemConstraints The constraints of the device's camera system, used to determine
+ * available test patterns.
+ * @param cameraAppSettings The current application and camera settings, used to get the selected
+ * test pattern and current lens.
+ * @param cameraState The real-time state from the camera, providing information like video
+ * resolution, camera IDs, and zoom ratio.
+ * @param debugHidingComponents A boolean indicating if non-debug UI components are currently hidden.
+ * @param cameraPropertiesJSON A JSON string representing the detailed properties of the camera.
+ *
+ * @return A [DebugUiState.Enabled.Open] object fully populated with the current debug information.
+ */
 fun DebugUiState.Enabled.Open.Companion.from(
     systemConstraints: CameraSystemConstraints,
     cameraAppSettings: CameraAppSettings,
@@ -57,6 +75,20 @@ fun DebugUiState.Enabled.Open.Companion.from(
     )
 }
 
+/**
+ * Creates a [DebugUiState.Enabled.Closed] state from the current camera state.
+ *
+ * This function gathers the minimal information needed for the collapsed (or partially visible)
+ * debug UI overlay. It provides key details like camera IDs and zoom ratio without the overhead
+of
+ * the full, open debug view.
+ *
+ * @param cameraState The real-time state from the camera, providing camera IDs and zoom ratio.
+ * @param lensFacing The currently active [LensFacing] value.
+ * @param debugHidingComponents A boolean indicating if non-debug UI components are currently hidden.
+ *
+ * @return A [DebugUiState.Enabled.Closed] object with essential debug information.
+ */
 fun DebugUiState.Enabled.Closed.Companion.from(
     cameraState: CameraState,
     lensFacing: LensFacing,
diff --git a/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/ElapsedTimeUiStateAdapter.kt b/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/ElapsedTimeUiStateAdapter.kt
index 17556ca29..0e52dae88 100644
--- a/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/ElapsedTimeUiStateAdapter.kt
+++ b/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/ElapsedTimeUiStateAdapter.kt
@@ -19,6 +19,21 @@ import com.google.jetpackcamera.core.camera.CameraState
 import com.google.jetpackcamera.core.camera.VideoRecordingState
 import com.google.jetpackcamera.ui.uistate.capture.ElapsedTimeUiState
 
+/**
+ * Creates an [ElapsedTimeUiState] based on the current [CameraState].
+ *
+ * This function translates the [VideoRecordingState] from the core camera layer into a UI-specific
+ * state for displaying the elapsed time of a video recording. It handles different recording
+ * phases: active recording, the final time after recording stops, and the initial state when
+ * a recording is starting.
+ *
+ * @param cameraState The real-time state from the camera, which includes the video recording status.
+ *
+ * @return An [ElapsedTimeUiState.Enabled] state containing the elapsed time in nanoseconds.
+ *         - For [VideoRecordingState.Active], it provides the ongoing elapsed time.
+ *         - For [VideoRecording_State.Inactive], it provides the final duration of the last recording.
+ *         - For [VideoRecordingState.Starting], it provides an initial value of 0.
+ */
 fun ElapsedTimeUiState.Companion.from(cameraState: CameraState): ElapsedTimeUiState {
     val videoRecordingState = cameraState.videoRecordingState
     return when (videoRecordingState) {
diff --git a/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/FlashModeUiStateAdapter.kt b/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/FlashModeUiStateAdapter.kt
index d2c72e424..1be7962b1 100644
--- a/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/FlashModeUiStateAdapter.kt
+++ b/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/FlashModeUiStateAdapter.kt
@@ -36,6 +36,20 @@ private val ORDERED_UI_SUPPORTED_FLASH_MODES = listOf(
     FlashMode.LOW_LIGHT_BOOST
 )
 
+/**
+ * Creates the initial [FlashModeUiState] from the given camera settings and system constraints.
+ *
+ * This factory function determines the set of available flash modes based on hardware support
+ * and current camera settings (like HDR or concurrent mode). If only [FlashMode.OFF] is available,
+ * or no modes are supported, it returns [FlashModeUiState.Unavailable].
+ *
+ * @param cameraAppSettings The current settings of the camera, used to determine which flash modes
+ * might be disabled due to other active settings (e.g., HDR).
+ * @param systemConstraints The hardware capabilities of the camera system, used to get the list
+ * of supported flash modes for the current lens.
+ * @return A [FlashModeUiState] which is either [Available] if multiple flash modes can be shown,
+ * or [Unavailable] if the flash controls should be hidden.
+ */
 fun FlashModeUiState.Companion.from(
     cameraAppSettings: CameraAppSettings,
     systemConstraints: CameraSystemConstraints
@@ -81,6 +95,20 @@ fun FlashModeUiState.Companion.from(
     }
 }
 
+/**
+ * Updates an existing [FlashModeUiState] based on new camera settings and state.
+ *
+ * This function efficiently updates the flash UI state without recreating it from scratch if
+ * possible. It checks for changes in supported modes, selected mode, and the real-time status
+ * of Low Light Boost.
+ *
+ * @param cameraAppSettings The current application settings for the camera.
+ * @param systemConstraints The hardware capabilities of the camera system.
+ * @param cameraState The real-time state from the camera, used to check [LowLightBoostState].
+ * @return An updated [FlashModeUiState]. This may be the same instance if no relevant
+ * state has changed, a copied instance with minor updates, or a completely new instance if
+ * supported flash modes have changed.
+ */
 fun FlashModeUiState.updateFrom(
     cameraAppSettings: CameraAppSettings,
     systemConstraints: CameraSystemConstraints,
diff --git a/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/FlipLensUiStateAdapter.kt b/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/FlipLensUiStateAdapter.kt
index 4b19b5b45..c130f35cd 100644
--- a/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/FlipLensUiStateAdapter.kt
+++ b/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/FlipLensUiStateAdapter.kt
@@ -27,6 +27,20 @@ private val ORDERED_UI_SUPPORTED_LENS_FACINGS = listOf(
 
 )
 
+/**
+ * Creates a [FlipLensUiState] based on the current camera settings and system constraints.
+ *
+ * This function determines the UI state for the lens flipping control (e.g., front/back camera
+ * button). It gathers the list of all physically available lenses from the system constraints
+ * and combines it with the currently selected lens from the application settings.
+ *
+ * @param cameraAppSettings The current application settings, used to determine the currently
+ * selected [LensFacing].
+ * @param systemConstraints The hardware capabilities of the camera system, used to get the list
+ * of all available lenses on the device.
+ * @return A [FlipLensUiState.Available] object containing the currently selected lens and a list
+ * of all available lenses for the UI to display.
+ */
 fun FlipLensUiState.Companion.from(
     cameraAppSettings: CameraAppSettings,
     systemConstraints: CameraSystemConstraints
diff --git a/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/FocusMeteringUiStateAdapter.kt b/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/FocusMeteringUiStateAdapter.kt
index a6986dfc8..abc9620f2 100644
--- a/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/FocusMeteringUiStateAdapter.kt
+++ b/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/FocusMeteringUiStateAdapter.kt
@@ -20,6 +20,19 @@ import com.google.jetpackcamera.core.camera.CameraState
 import com.google.jetpackcamera.core.camera.FocusState
 import com.google.jetpackcamera.ui.uistate.capture.FocusMeteringUiState
 
+/**
+ * Updates an existing [FocusMeteringUiState] based on a new [CameraState].
+ *
+ * This function provides an efficient way to update the focus UI state by comparing the incoming
+ * camera state with the current UI state. It avoids creating a new object if the underlying
+ * focus parameters (like coordinates and status) have not changed, reducing unnecessary
+ * recompositions. If the state has meaningfully changed, it delegates to the [from] factory
+ * function to create a new, updated state.
+ *
+ * @param cameraState The new, real-time state from the camera.
+ * @return The existing [FocusMeteringUiState] instance if no change is detected, or a new
+ *         [FocusMeteringUiState] reflecting the updated camera focus state.
+ */
 fun FocusMeteringUiState.updateFrom(cameraState: CameraState): FocusMeteringUiState {
     val focusState = cameraState.focusState
     return when (this) {
@@ -45,6 +58,17 @@ fun FocusMeteringUiState.updateFrom(cameraState: CameraState): FocusMeteringUiSt
     }
 }
 
+/**
+ * Creates a [FocusMeteringUiState] from the given [CameraState].
+ *
+ * This factory function translates the low-level [FocusState] from the core camera layer into its
+ * corresponding UI representation. It maps the coordinates and status (e.g., RUNNING, SUCCESS)
+ * to the appropriate [FocusMeteringUiState] subtype, which can be either [FocusMeteringUiState.Unspecified]
+ * or [FocusMeteringUiState.Specified].
+ *
+ * @param cameraState The real-time state from the camera containing the focus information.
+ * @return A [FocusMeteringUiState] that represents the current focus state for the UI.
+ */
 fun FocusMeteringUiState.Companion.from(cameraState: CameraState): FocusMeteringUiState {
     return when (val focusState = cameraState.focusState) {
         is FocusState.Unspecified -> FocusMeteringUiState.Unspecified
diff --git a/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/HdrUiStateAdapter.kt b/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/HdrUiStateAdapter.kt
index 4c990b3a4..e40480d00 100644
--- a/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/HdrUiStateAdapter.kt
+++ b/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/HdrUiStateAdapter.kt
@@ -26,6 +26,30 @@ import com.google.jetpackcamera.settings.model.CameraSystemConstraints
 import com.google.jetpackcamera.settings.model.forCurrentLens
 import com.google.jetpackcamera.ui.uistate.capture.HdrUiState
 
+/**
+ * Creates an [HdrUiState] based on the current camera settings, system constraints, and capture mode.
+ *
+ * This function determines whether the High Dynamic Range (HDR) feature is available for the user
+ * to interact with. The availability depends on a combination of hardware support for specific
+ * HDR formats ([DynamicRange.HLG10] for video, [ImageOutputFormat.JPEG_ULTRA_HDR] for images) and
+ * various other settings that may conflict with HDR, such as flash mode or concurrent camera mode.
+ *
+ * The logic is tailored to the [ExternalCaptureMode]:
+ * - **ImageCapture / MultipleImageCapture**: Checks for `JPEG_ULTRA_HDR` support.
+ * - **VideoCapture**: Checks for `HLG10` dynamic range support.
+ * - **Standard**: Checks for support for either `HLG10` or `JPEG_ULTRA_HDR`.
+ *
+ * In all cases, HDR is disabled if `LOW_LIGHT_BOOST` flash mode is active. For video and standard
+ * modes, it is also disabled if concurrent camera mode is active.
+ *
+ * @param cameraAppSettings The current application and camera settings.
+ * @param systemConstraints The capabilities and limitations of the device's camera hardware.
+ * @param externalCaptureMode The mode indicating how the camera was launched (e.g., via an
+ * external intent), which influences which HDR formats are relevant.
+ *
+ * @return [HdrUiState.Available] if the feature is supported and not blocked by other settings,
+ * otherwise returns [HdrUiState.Unavailable].
+ */
 fun HdrUiState.Companion.from(
     cameraAppSettings: CameraAppSettings,
     systemConstraints: CameraSystemConstraints,
diff --git a/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/ImageWellUiStateAdapter.kt b/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/ImageWellUiStateAdapter.kt
index adea8f711..c8e73d7f9 100644
--- a/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/ImageWellUiStateAdapter.kt
+++ b/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/ImageWellUiStateAdapter.kt
@@ -19,6 +19,19 @@ import com.google.jetpackcamera.core.camera.VideoRecordingState
 import com.google.jetpackcamera.data.media.MediaDescriptor
 import com.google.jetpackcamera.ui.uistate.capture.ImageWellUiState
 
+/**
+ * Creates an [ImageWellUiState] based on the most recently captured media and video recording status.
+ *
+ * This function determines the state of the image well component, which displays a thumbnail of
+ * the last captured photo or video. The image well is only shown if there is a valid media
+ * thumbnail available and if a video recording is not currently in progress.
+ *
+ * @param mediaDescriptor The descriptor for the most recently captured media, which may contain a
+ *   thumbnail.
+ * @param videoRecordingState The current state of video recording.
+ * @return [ImageWellUiState.LastCapture] containing the [mediaDescriptor] if a thumbnail exists
+ *   and recording is inactive, otherwise returns [ImageWellUiState.Unavailable].
+ */
 fun ImageWellUiState.Companion.from(
     mediaDescriptor: MediaDescriptor,
     videoRecordingState: VideoRecordingState
diff --git a/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/PreviewMode.kt b/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/PreviewMode.kt
deleted file mode 100644
index b6474417b..000000000
--- a/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/PreviewMode.kt
+++ /dev/null
@@ -1,23 +0,0 @@
-/*
- * Copyright (C) 2025 The Android Open Source Project
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *      http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-package com.google.jetpackcamera.ui.uistateadapter.capture
-
-enum class PreviewMode {
-    STANDARD,
-    EXTERNAL_VIDEO_CAPTURE,
-    EXTERNAL_IMAGE_CAPTURE,
-    EXTERNAL_MULTIPLE_IMAGE_CAPTURE
-}
diff --git a/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/StabilizationUiStateAdapter.kt b/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/StabilizationUiStateAdapter.kt
index 3d32b6394..fea7deefd 100644
--- a/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/StabilizationUiStateAdapter.kt
+++ b/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/StabilizationUiStateAdapter.kt
@@ -20,6 +20,32 @@ import com.google.jetpackcamera.model.StabilizationMode
 import com.google.jetpackcamera.settings.model.CameraAppSettings
 import com.google.jetpackcamera.ui.uistate.capture.StabilizationUiState
 
+/**
+ * Creates a [StabilizationUiState] based on the current camera settings and real-time camera state.
+ *
+ * This function translates the user's intended stabilization setting (`expectedMode`) and the
+ * camera's actual, currently active stabilization (`actualMode`) into a UI-specific state.
+ * It handles the differences between what the user has selected and what the hardware is
+ * currently providing.
+ *
+ * @param cameraAppSettings The current application settings, which contain the user's desired
+ *   [StabilizationMode].
+ * @param cameraState The real-time state from the camera, which reports the currently active
+ *   [StabilizationMode].
+ *
+ * @return A [StabilizationUiState] representing the current stabilization status.
+ * - [StabilizationUiState.Disabled] if the user setting is `OFF`, or if `AUTO` is selected but
+ *   the camera is not actively using `ON` or `OPTICAL` stabilization.
+ * - [StabilizationUiState.Auto] if the user setting is `AUTO` and the camera has resolved it
+ *   to an active stabilization mode (e.g., `ON` or `OPTICAL`).
+ * - [StabilizationUiState.Specific] if the user has selected a specific mode like `ON`,
+ *   `OPTICAL`, or `HIGH_QUALITY`. The `active` property will indicate if the camera's
+ *   `actualMode` matches the user's `expectedMode`.
+ *
+ * @throws IllegalStateException if the `cameraState` reports `StabilizationMode.AUTO`, as the
+ *   camera implementation should always resolve `AUTO` to a specific, active mode (`ON`,
+ *   `OPTICAL`, or `OFF`).
+ */
 fun StabilizationUiState.Companion.from(
     cameraAppSettings: CameraAppSettings,
     cameraState: CameraState
diff --git a/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/StreamConfigsUiStateAdapter.kt b/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/StreamConfigsUiStateAdapter.kt
index 661a443de..3a26a3c70 100644
--- a/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/StreamConfigsUiStateAdapter.kt
+++ b/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/StreamConfigsUiStateAdapter.kt
@@ -27,6 +27,24 @@ private val ORDERED_UI_SUPPORTED_STREAM_CONFIGS = listOf(
     StreamConfig.MULTI_STREAM
 )
 
+/**
+ * Creates a [StreamConfigUiState] based on the provided camera settings.
+ *
+ * This function determines the availability and selection state of stream configurations, which
+ * control whether the camera operates using a single stream or multiple streams. The UI for this
+ * setting is made available only if more than one stream configuration is supported. The control
+ * is marked as inactive (disabled) if concurrent camera mode is active or if the image format
+ * is set to Ultra HDR, as these features are incompatible with changing the stream configuration.
+ *
+ * @param cameraAppSettings The current application settings, which provide the selected
+ *   [StreamConfig], [ConcurrentCameraMode], and [ImageOutputFormat].
+ *
+ * @return A [StreamConfigUiState] which will be:
+ * - [StreamConfigUiState.Available] if multiple stream configs are supported, containing the
+ *   current selection, the list of available options, and whether the UI control should be active.
+ * - [StreamConfigUiState.Unavailable] if only one or zero stream configs are supported, meaning
+ *   the user cannot change this setting.
+ */
 fun StreamConfigUiState.Companion.from(cameraAppSettings: CameraAppSettings): StreamConfigUiState {
     return createFrom(
         cameraAppSettings.streamConfig,
diff --git a/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/ZoomControlUiStateAdapter.kt b/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/ZoomControlUiStateAdapter.kt
index 980a23341..d7b95b525 100644
--- a/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/ZoomControlUiStateAdapter.kt
+++ b/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/ZoomControlUiStateAdapter.kt
@@ -21,6 +21,29 @@ import com.google.jetpackcamera.settings.model.CameraAppSettings
 import com.google.jetpackcamera.settings.model.CameraSystemConstraints
 import com.google.jetpackcamera.ui.uistate.capture.ZoomControlUiState
 
+/**
+ * Creates a [ZoomControlUiState] from various camera and application sources.
+ *
+ * This function is responsible for creating the UI state for the zoom controls (e.g., the 0.5x, 1x,
+ * 2x buttons). It determines the available zoom levels based on the hardware's supported zoom
+ * range for the currently active lens.
+ *
+ * If the camera lens does not support zooming (i.e., the zoom range is a single value), this
+ * function will return [ZoomControlUiState.Disabled]. Otherwise, it calculates a list of discrete
+ * zoom levels to display to the user (e.g., 0.5x, 1x, 2x, 5x) based on the supported range.
+ *
+ * @param animateZoomState An optional target zoom ratio for an ongoing animation. If non-null, the
+ *   UI can use this to show an animation progressing towards the target.
+ * @param systemConstraints The capabilities of the device's camera hardware, used to find the
+ *   supported zoom range for the current lens.
+ * @param cameraAppSettings The current application settings, providing the selected lens facing
+ *   and default zoom ratios.
+ * @param cameraState The real-time state from the camera, providing the current actual zoom ratio.
+ * @return A [ZoomControlUiState] which is either:
+ * - [ZoomControlUiState.Enabled] containing the calculated zoom levels, current zoom ratio, and
+ *   other parameters for the UI.
+ * - [ZoomControlUiState.Disabled] if the current lens does not support zooming.
+ */
 fun ZoomControlUiState.Companion.from(
     animateZoomState: Float?,
     systemConstraints: CameraSystemConstraints,
diff --git a/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/ZoomUiStateAdapter.kt b/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/ZoomUiStateAdapter.kt
index a59e617a1..80f9c07cd 100644
--- a/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/ZoomUiStateAdapter.kt
+++ b/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/ZoomUiStateAdapter.kt
@@ -21,6 +21,21 @@ import com.google.jetpackcamera.model.LensFacing
 import com.google.jetpackcamera.settings.model.CameraSystemConstraints
 import com.google.jetpackcamera.ui.uistate.capture.ZoomUiState
 
+/**
+ * Creates a [ZoomUiState] from various camera and application sources.
+ *
+ * This function is responsible for creating the UI state for zoom-related information, such as the
+ * zoom slider. It gathers the supported zoom range for the current lens and combines it with the
+ * camera's real-time zoom ratio and linear zoom value.
+ *
+ * @param systemConstraints The capabilities of the device's camera hardware, used to find the
+ *   supported zoom range for the current lens.
+ * @param lensFacing The currently active [LensFacing] to look up the correct constraints and state.
+ * @param cameraState The real-time state from the camera, providing the current zoom ratio and
+ *   linear zoom value.
+ * @return A [ZoomUiState.Enabled] object containing the zoom range, current zoom ratio, and current
+ *   linear zoom value for the UI.
+ */
 fun ZoomUiState.Companion.from(
     systemConstraints: CameraSystemConstraints,
     lensFacing: LensFacing,

From dfb8a2229f752580b568837446ab175e6434dbc3 Mon Sep 17 00:00:00 2001
From: David Jia <davidjia@google.com>
Date: Fri, 6 Feb 2026 11:49:19 -0800
Subject: [PATCH 2/3] address gemini comments

---
 .../ui/uistateadapter/capture/AudioUiStateAdapter.kt         | 5 +++--
 .../ui/uistateadapter/capture/DebugUiStateAdapter.kt         | 4 ----
 .../ui/uistateadapter/capture/ElapsedTimeUiStateAdapter.kt   | 2 +-
 3 files changed, 4 insertions(+), 7 deletions(-)

diff --git a/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/AudioUiStateAdapter.kt b/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/AudioUiStateAdapter.kt
index 32e81431c..a2ffc0f07 100644
--- a/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/AudioUiStateAdapter.kt
+++ b/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/AudioUiStateAdapter.kt
@@ -24,8 +24,9 @@ import com.google.jetpackcamera.ui.uistate.capture.AudioUiState
  * Creates an [AudioUiState] from the given camera application settings.
  *
  * @param cameraAppSettings The current settings of the camera application.
- * @return [AudioUiState.Enabled] if audio is enabled in the settings, otherwise
- * [AudioUiState.Disabled].
+ * @param cameraState The current state of the camera, used to get the audio amplitude.
+ * @return [AudioUiState.Enabled.On] if audio is enabled, containing the current amplitude,
+ * or [AudioUiState.Enabled.Mute] if audio is disabled.
  */
 fun AudioUiState.Companion.from(
     cameraAppSettings: CameraAppSettings,
diff --git a/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/DebugUiStateAdapter.kt b/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/DebugUiStateAdapter.kt
index b49a9d3a5..57ff410dc 100644
--- a/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/DebugUiStateAdapter.kt
+++ b/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/DebugUiStateAdapter.kt
@@ -77,10 +77,6 @@ fun debugUiState(
 /**
  * Constructs a [DebugUiState] based on the current camera and application state.
  *
- * This is a private factory function that determines whether the debug UI should be fully
- * enabled and open, enabled but closed, or completely disabled. It gathers and transforms
- * the necessary data for the UI.
- *
  * @param systemConstraints The system-level constraints for the current camera.
  * @param cameraAppSettings The current application-level camera settings.
  * @param cameraState The real-time state of the camera.
diff --git a/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/ElapsedTimeUiStateAdapter.kt b/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/ElapsedTimeUiStateAdapter.kt
index 0e52dae88..370814a34 100644
--- a/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/ElapsedTimeUiStateAdapter.kt
+++ b/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/ElapsedTimeUiStateAdapter.kt
@@ -31,7 +31,7 @@ import com.google.jetpackcamera.ui.uistate.capture.ElapsedTimeUiState
  *
  * @return An [ElapsedTimeUiState.Enabled] state containing the elapsed time in nanoseconds.
  *         - For [VideoRecordingState.Active], it provides the ongoing elapsed time.
- *         - For [VideoRecording_State.Inactive], it provides the final duration of the last recording.
+ *         - For [VideoRecordingState.Inactive], it provides the final duration of the last recording.
  *         - For [VideoRecordingState.Starting], it provides an initial value of 0.
  */
 fun ElapsedTimeUiState.Companion.from(cameraState: CameraState): ElapsedTimeUiState {

From 67036d052024e16224feb6e4acbb39de6173401b Mon Sep 17 00:00:00 2001
From: David Jia <davidjia@google.com>
Date: Wed, 18 Feb 2026 14:34:50 -0800
Subject: [PATCH 3/3] address comments

---
 .../feature/preview/PreviewScreen.kt          |  2 +-
 .../feature/preview/PreviewViewModel.kt       |  2 +-
 .../ui/components/capture/ImageWell.kt        |  4 ++--
 .../ui/uistate/capture/ImageWellUiState.kt    |  2 +-
 .../capture/CaptureButtonUiStateAdapter.kt    |  4 ++--
 .../capture/FocusMeteringUiStateAdapter.kt    |  6 +-----
 .../capture/ImageWellUiStateAdapter.kt        | 19 ++++++++++---------
 .../capture/ImageWellUiStateAdapterTest.kt    |  2 +-
 8 files changed, 19 insertions(+), 22 deletions(-)

diff --git a/feature/preview/src/main/java/com/google/jetpackcamera/feature/preview/PreviewScreen.kt b/feature/preview/src/main/java/com/google/jetpackcamera/feature/preview/PreviewScreen.kt
index ef6940968..b899cdaaf 100644
--- a/feature/preview/src/main/java/com/google/jetpackcamera/feature/preview/PreviewScreen.kt
+++ b/feature/preview/src/main/java/com/google/jetpackcamera/feature/preview/PreviewScreen.kt
@@ -624,7 +624,7 @@ private fun ContentScreen(
         },
         imageWell = { modifier ->
             if (captureUiState.externalCaptureMode == ExternalCaptureMode.Standard) {
-                (captureUiState.imageWellUiState as? ImageWellUiState.LastCapture)?.let {
+                (captureUiState.imageWellUiState as? ImageWellUiState.Content)?.let {
                     ImageWell(
                         modifier = modifier,
                         imageWellUiState = it,
diff --git a/feature/preview/src/main/java/com/google/jetpackcamera/feature/preview/PreviewViewModel.kt b/feature/preview/src/main/java/com/google/jetpackcamera/feature/preview/PreviewViewModel.kt
index d3c46b453..090dfa462 100644
--- a/feature/preview/src/main/java/com/google/jetpackcamera/feature/preview/PreviewViewModel.kt
+++ b/feature/preview/src/main/java/com/google/jetpackcamera/feature/preview/PreviewViewModel.kt
@@ -225,7 +225,7 @@ class PreviewViewModel @Inject constructor(
      */
     fun imageWellToRepository() {
         (captureUiState.value as? CaptureUiState.Ready)
-            ?.let { it.imageWellUiState as? ImageWellUiState.LastCapture }
+            ?.let { it.imageWellUiState as? ImageWellUiState.Content }
             ?.let { postCurrentMediaToMediaRepository(it.mediaDescriptor) }
     }
 
diff --git a/ui/components/capture/src/main/java/com/google/jetpackcamera/ui/components/capture/ImageWell.kt b/ui/components/capture/src/main/java/com/google/jetpackcamera/ui/components/capture/ImageWell.kt
index 98e2e856c..fea778419 100644
--- a/ui/components/capture/src/main/java/com/google/jetpackcamera/ui/components/capture/ImageWell.kt
+++ b/ui/components/capture/src/main/java/com/google/jetpackcamera/ui/components/capture/ImageWell.kt
@@ -51,7 +51,7 @@ import com.google.jetpackcamera.ui.uistate.capture.ImageWellUiState
 @OptIn(ExperimentalMaterial3ExpressiveApi::class, ExperimentalAnimationApi::class)
 @Composable
 fun ImageWell(
-    imageWellUiState: ImageWellUiState.LastCapture,
+    imageWellUiState: ImageWellUiState.Content,
     onClick: () -> Unit,
     modifier: Modifier = Modifier,
     shape: Shape = RoundedCornerShape(16.dp),
@@ -100,7 +100,7 @@ private fun ImageWellPreview() {
         uri = Uri.EMPTY,
         thumbnail = previewBitmap
     )
-    val imageWellUiState = ImageWellUiState.LastCapture(
+    val imageWellUiState = ImageWellUiState.Content(
         mediaDescriptor = mediaDescriptor
     )
 
diff --git a/ui/uistate/capture/src/main/java/com/google/jetpackcamera/ui/uistate/capture/ImageWellUiState.kt b/ui/uistate/capture/src/main/java/com/google/jetpackcamera/ui/uistate/capture/ImageWellUiState.kt
index 1f1056cef..49546c0cf 100644
--- a/ui/uistate/capture/src/main/java/com/google/jetpackcamera/ui/uistate/capture/ImageWellUiState.kt
+++ b/ui/uistate/capture/src/main/java/com/google/jetpackcamera/ui/uistate/capture/ImageWellUiState.kt
@@ -20,7 +20,7 @@ import com.google.jetpackcamera.data.media.MediaDescriptor
 sealed interface ImageWellUiState {
     data object Unavailable : ImageWellUiState
 
-    data class LastCapture(val mediaDescriptor: MediaDescriptor.Content) : ImageWellUiState
+    data class Content(val mediaDescriptor: MediaDescriptor.Content) : ImageWellUiState
 
     companion object
 }
diff --git a/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/CaptureButtonUiStateAdapter.kt b/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/CaptureButtonUiStateAdapter.kt
index 4f35f4323..5f68b1243 100644
--- a/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/CaptureButtonUiStateAdapter.kt
+++ b/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/CaptureButtonUiStateAdapter.kt
@@ -23,8 +23,8 @@ import com.google.jetpackcamera.ui.uistate.capture.CaptureButtonUiState
 /**
  * Creates a [CaptureButtonUiState] based on the current camera settings and state.
  *
- * This function determines the appropriate UI state for the main capture button, which can change
- * depending on the current capture mode, video recording status, and whether the recording is locked.
+ * This function determines the UI state for the capture button based on the capture mode, video
+ * recording status, and whether the recording has been locked.
  *
  * @param cameraAppSettings The current application settings, used to determine the capture mode.
  * @param cameraState The current state of the camera, used to check video recording status.
diff --git a/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/FocusMeteringUiStateAdapter.kt b/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/FocusMeteringUiStateAdapter.kt
index abc9620f2..ed389ce5d 100644
--- a/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/FocusMeteringUiStateAdapter.kt
+++ b/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/FocusMeteringUiStateAdapter.kt
@@ -23,11 +23,7 @@ import com.google.jetpackcamera.ui.uistate.capture.FocusMeteringUiState
 /**
  * Updates an existing [FocusMeteringUiState] based on a new [CameraState].
  *
- * This function provides an efficient way to update the focus UI state by comparing the incoming
- * camera state with the current UI state. It avoids creating a new object if the underlying
- * focus parameters (like coordinates and status) have not changed, reducing unnecessary
- * recompositions. If the state has meaningfully changed, it delegates to the [from] factory
- * function to create a new, updated state.
+ * This factory function translates the [FocusState] into its corresponding UI representation.
  *
  * @param cameraState The new, real-time state from the camera.
  * @return The existing [FocusMeteringUiState] instance if no change is detected, or a new
diff --git a/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/ImageWellUiStateAdapter.kt b/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/ImageWellUiStateAdapter.kt
index c8e73d7f9..035231eb3 100644
--- a/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/ImageWellUiStateAdapter.kt
+++ b/ui/uistateadapter/capture/src/main/java/com/google/jetpackcamera/ui/uistateadapter/capture/ImageWellUiStateAdapter.kt
@@ -20,17 +20,18 @@ import com.google.jetpackcamera.data.media.MediaDescriptor
 import com.google.jetpackcamera.ui.uistate.capture.ImageWellUiState
 
 /**
- * Creates an [ImageWellUiState] based on the most recently captured media and video recording status.
+ * Creates an [ImageWellUiState] for a given [MediaDescriptor] and [VideoRecordingState].
  *
- * This function determines the state of the image well component, which displays a thumbnail of
- * the last captured photo or video. The image well is only shown if there is a valid media
- * thumbnail available and if a video recording is not currently in progress.
+ * This function determines the state of the image well, a component that displays the
+ * [MediaDescriptor]'s thumbnail. This state will be unavailable if any of the following are true:
+ * - mediaDescriptor is not MediaDescriptor.Content
+ * - mediaDescriptor does not have a thumbnail
  *
- * @param mediaDescriptor The descriptor for the most recently captured media, which may contain a
- *   thumbnail.
+ * @param mediaDescriptor the media's correlating [MediaDescriptor]
  * @param videoRecordingState The current state of video recording.
- * @return [ImageWellUiState.LastCapture] containing the [mediaDescriptor] if a thumbnail exists
- *   and recording is inactive, otherwise returns [ImageWellUiState.Unavailable].
+ * @return [ImageWellUiState.Content] only if the mediaDescriptor is MediaDescriptor.Content,
+ *  has a non-null thumbnail, and video recording state is inactive.
+ *  otherwise return [ImageWellUiState.Unavailable]
  */
 fun ImageWellUiState.Companion.from(
     mediaDescriptor: MediaDescriptor,
@@ -40,7 +41,7 @@ fun ImageWellUiState.Companion.from(
         mediaDescriptor.thumbnail != null &&
         videoRecordingState is VideoRecordingState.Inactive
     ) {
-        ImageWellUiState.LastCapture(mediaDescriptor = mediaDescriptor)
+        ImageWellUiState.Content(mediaDescriptor = mediaDescriptor)
     } else {
         ImageWellUiState.Unavailable
     }
diff --git a/ui/uistateadapter/capture/src/test/java/com/google/jetpackcamera/ui/uistateadapter/capture/ImageWellUiStateAdapterTest.kt b/ui/uistateadapter/capture/src/test/java/com/google/jetpackcamera/ui/uistateadapter/capture/ImageWellUiStateAdapterTest.kt
index 078ddb64b..015368884 100644
--- a/ui/uistateadapter/capture/src/test/java/com/google/jetpackcamera/ui/uistateadapter/capture/ImageWellUiStateAdapterTest.kt
+++ b/ui/uistateadapter/capture/src/test/java/com/google/jetpackcamera/ui/uistateadapter/capture/ImageWellUiStateAdapterTest.kt
@@ -40,7 +40,7 @@ class ImageWellUiStateAdapterTest {
         val result = ImageWellUiState.from(mediaDescriptor, videoRecordingState)
 
         // Then
-        assertThat(result).isEqualTo(ImageWellUiState.LastCapture(mediaDescriptor))
+        assertThat(result).isEqualTo(ImageWellUiState.Content(mediaDescriptor))
     }
 
     @Test