diff --git a/libraries/common/src/main/java/androidx/media3/common/util/UnstableApi.java b/libraries/common/src/main/java/androidx/media3/common/util/UnstableApi.java
index 3ea66b64ad..c05311052d 100644
--- a/libraries/common/src/main/java/androidx/media3/common/util/UnstableApi.java
+++ b/libraries/common/src/main/java/androidx/media3/common/util/UnstableApi.java
@@ -55,10 +55,10 @@ import java.lang.annotation.Target;
  * <p>By default usages of APIs annotated with this annotation generate lint errors in Gradle and
  * Android Studio, in order to alert developers to the risk of breaking changes.
  *
- * <p>Individual usage sites can be opted-in to suppress the lint error by using the {@link
- * androidx.annotation.OptIn} annotation.
+ * <p>Individual usage sites or whole packages can be opted-in to suppress the lint error by using
+ * the {@link androidx.annotation.OptIn} annotation.
  *
- * <p>In Java:
+ * <p>In a Java class:
  *
  * <pre>{@code
  * import androidx.annotation.OptIn;
@@ -68,6 +68,16 @@ import java.lang.annotation.Target;
  * private void methodUsingUnstableApis() { ... }
  * }</pre>
  *
+ * <p>In a {@code package-info.java} file, to opt-in a whole package:
+ *
+ * <pre>{@code
+ * @OptIn(markerClass = UnstableApi.class)
+ * package name.of.your.package;
+ *
+ * import androidx.annotation.OptIn;
+ * import androidx.media3.common.util.UnstableApi;
+ * }</pre>
+ *
  * <p>In Kotlin:
  *
  * <pre>{@code