diff --git a/core/java/android/view/Surface.java b/core/java/android/view/Surface.java
index aa3c9d6e14f99..ff2d2eb3d3345 100644
--- a/core/java/android/view/Surface.java
+++ b/core/java/android/view/Surface.java
@@ -936,18 +936,21 @@ public class Surface implements Parcelable {
      * @param frameRate The intended frame rate of this surface, in frames per second. 0
      * is a special value that indicates the app will accept the system's choice for the
      * display frame rate, which is the default behavior if this function isn't
-     * called. The frameRate param does <em>not</em> need to be a valid refresh rate for
-     * this device's display - e.g., it's fine to pass 30fps to a device that can only run
+     * called. The <code>frameRate</code> parameter does <em>not</em> need to be a valid refresh
+     * rate for this device's display - e.g., it's fine to pass 30fps to a device that can only run
      * the display at 60fps.
      *
      * @param compatibility The frame rate compatibility of this surface. The
      * compatibility value may influence the system's choice of display frame rate.
+     * This parameter is ignored when <code>frameRate</code> is 0.
      *
-     * @param changeFrameRateStrategy Whether display refresh rate transitions should be seamless. A
-     * seamless transition is one that doesn't have any visual interruptions, such as a black
-     * screen for a second or two.
+     * @param changeFrameRateStrategy Whether display refresh rate transitions caused by this
+     * surface should be seamless. A seamless transition is one that doesn't have any visual
+     * interruptions, such as a black screen for a second or two. This parameter is ignored when
+     * <code>frameRate</code> is 0.
      *
-     * @throws IllegalArgumentException If frameRate or compatibility are invalid.
+     * @throws IllegalArgumentException If <code>frameRate</code>, <code>compatibility</code> or
+     * <code>changeFrameRateStrategy</code> are invalid.
      */
     public void setFrameRate(@FloatRange(from = 0.0) float frameRate,
             @FrameRateCompatibility int compatibility,
diff --git a/core/java/android/view/SurfaceControl.java b/core/java/android/view/SurfaceControl.java
index 3ff7a65b6c6a9..ac70dff4f03e5 100644
--- a/core/java/android/view/SurfaceControl.java
+++ b/core/java/android/view/SurfaceControl.java
@@ -3298,20 +3298,26 @@ public final class SurfaceControl implements Parcelable {
          * because the system may change the display refresh rate, calls to this function may result
          * in changes to Choreographer callback timings, and changes to the time interval at which
          * the system releases buffers back to the application.
+         * <p>
+         * Note that this only has an effect for surfaces presented on the display. If this
+         * surface is consumed by something other than the system compositor, e.g. a media
+         * codec, this call has no effect.
          *
          * @param sc The SurfaceControl to specify the frame rate of.
          * @param frameRate The intended frame rate for this surface, in frames per second. 0 is a
          *                  special value that indicates the app will accept the system's choice for
          *                  the display frame rate, which is the default behavior if this function
-         *                  isn't called. The frameRate param does <em>not</em> need to be a valid
-         *                  refresh rate for this device's display - e.g., it's fine to pass 30fps
-         *                  to a device that can only run the display at 60fps.
+         *                  isn't called. The <code>frameRate</code> param does <em>not</em> need
+         *                  to be a valid refresh rate for this device's display - e.g., it's fine
+         *                  to pass 30fps to a device that can only run the display at 60fps.
          * @param compatibility The frame rate compatibility of this surface. The compatibility
          *                      value may influence the system's choice of display frame rate.
-         * @param changeFrameRateStrategy Whether display refresh rate transitions should be
-         *                                seamless. A seamless transition is one that doesn't have
-         *                                any visual interruptions, such as a black screen for a
-         *                                second or two.
+         *                      This parameter is ignored when <code>frameRate</code> is 0.
+         * @param changeFrameRateStrategy Whether display refresh rate transitions caused by this
+         *                                surface should be seamless. A seamless transition is one
+         *                                that doesn't have any visual interruptions, such as a
+         *                                black screen for a second or two. This parameter is
+         *                                ignored when <code>frameRate</code> is 0.
          * @return This transaction object.
          */
         @NonNull