From 2ec24ac55f6f1bd86c2cbeea7d204700e75ed548 Mon Sep 17 00:00:00 2001
From: ibaker <ibaker@google.com>
Date: Tue, 10 Oct 2023 06:32:52 -0700
Subject: [PATCH] Update `@UnstableApi` docs to include a `package-info.java`
 example

#minor-release

PiperOrigin-RevId: 572229092
(cherry picked from commit 7009c53c799171c4f8e418af5fdb31a6a5544ab9)
---
 .../androidx/media3/common/util/UnstableApi.java | 16 +++++++++++++---
 1 file changed, 13 insertions(+), 3 deletions(-)

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