diff --git a/core/java/android/view/Surface.java b/core/java/android/view/Surface.java
index 24bc308..f8c4d15 100644
--- a/core/java/android/view/Surface.java
+++ b/core/java/android/view/Surface.java
@@ -928,7 +928,9 @@
      * seamless transition is one that doesn't have any visual interruptions, such as a black
      * screen for a second or two. True indicates that any frame rate changes caused by this
      * request should be seamless. False indicates that non-seamless refresh rates are also
-     * acceptable.
+     * acceptable. Non-seamless switches might be used when the benefit of matching the content's
+     * frame rate outweighs the cost of the transition, for example when displaying
+     * long-running video content.
      *
      * @throws IllegalArgumentException If frameRate or compatibility are invalid.
      */
diff --git a/core/java/android/view/SurfaceControl.java b/core/java/android/view/SurfaceControl.java
index acd2507..efa33f7 100644
--- a/core/java/android/view/SurfaceControl.java
+++ b/core/java/android/view/SurfaceControl.java
@@ -3252,7 +3252,10 @@
          *                         interruptions, such as a black screen for a second or two. True
          *                         indicates that any frame rate changes caused by this request
          *                         should be seamless. False indicates that non-seamless refresh
-         *                         rates are also acceptable.
+         *                         rates are also acceptable. Non-seamless switches might be
+         *                         used when the benefit of matching the content's frame rate
+         *                         outweighs the cost of the transition, for example when
+         *                         displaying long-running video content.
          * @return This transaction object.
          */
         @NonNull